From e425c8f08183b333e56d5d3cfe74fc9e85a6c903 Mon Sep 17 00:00:00 2001 From: Lance Ball Date: Thu, 8 Oct 2020 04:58:17 -0400 Subject: [PATCH] src!: change all references of "repository" to "registry" for images (#156) When dealing with images, instead of referring to an image repository, let's instead use the more correct term "registry", even though we're actually using "registry/namespace" in most case. Signed-off-by: Lance Ball --- client.go | 10 +++---- client_test.go | 57 +++++++++++++++++++-------------------- cmd/build.go | 56 +++++++++++++++++++------------------- cmd/create.go | 28 +++++++++---------- cmd/deploy.go | 34 +++++++++++------------ cmd/root.go | 8 +++--- docs/commands.md | 22 +++++++-------- docs/integrators_guide.md | 2 +- function.go | 43 +++++++++++++++-------------- templates.go | 2 +- 10 files changed, 129 insertions(+), 133 deletions(-) diff --git a/client.go b/client.go index 9f6025827..a5e606d6b 100644 --- a/client.go +++ b/client.go @@ -28,7 +28,7 @@ type Client struct { describer Describer dnsProvider DNSProvider // Provider of DNS services templates string // path to extensible templates - repository string // default repo for OCI image tags + registry string // default registry for OCI image tags domainSearchLimit int // max recursion when deriving domain progressListener ProgressListener // progress listener } @@ -225,13 +225,13 @@ func WithTemplates(templates string) Option { } } -// WithRepository sets the default registry which is consulted when an image name/tag +// WithRegistry sets the default registry which is consulted when an image name/tag // is not explocitly provided. Can be fully qualified, including the registry // (ex: 'quay.io/myname') or simply the namespace 'myname' which indicates the // the use of the default registry. -func WithRepository(repository string) Option { +func WithRegistry(registry string) Option { return func(c *Client) { - c.repository = repository + c.registry = registry } } @@ -377,7 +377,7 @@ func (c *Client) Build(path string) (err error) { } // Derive Image from the path (precedence is given to extant config) - if f.Image, err = DerivedImage(path, c.repository); err != nil { + if f.Image, err = DerivedImage(path, c.registry); err != nil { return } diff --git a/client_test.go b/client_test.go index c9b82c67e..86390638f 100644 --- a/client_test.go +++ b/client_test.go @@ -11,10 +11,10 @@ import ( "github.com/boson-project/faas/mock" ) -// TestRepository for calculating destination image during tests. +// TestRegistry for calculating destination image during tests. // Will be optional once we support in-cluster container registries -// by default. See TestRepositoryRequired for details. -const TestRepository = "quay.io/alice" +// by default. See TestRegistryRequired for details. +const TestRegistry = "quay.io/alice" // TestCreate completes without error using all defaults and zero values. The base case. func TestCreate(t *testing.T) { @@ -25,7 +25,7 @@ func TestCreate(t *testing.T) { } defer os.RemoveAll(root) - client := faas.New(faas.WithRepository(TestRepository)) + client := faas.New(faas.WithRegistry(TestRegistry)) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) @@ -42,7 +42,7 @@ func TestCreateWritesTemplate(t *testing.T) { defer os.RemoveAll(root) // Create the function at root - client := faas.New(faas.WithRepository(TestRepository)) + client := faas.New(faas.WithRegistry(TestRegistry)) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) } @@ -125,7 +125,7 @@ func TestCreateDefaultRuntime(t *testing.T) { defer os.RemoveAll(root) // Create a new function at root with all defaults. - client := faas.New(faas.WithRepository(TestRepository)) + client := faas.New(faas.WithRegistry(TestRegistry)) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) } @@ -154,8 +154,7 @@ func TestCreateDefaultTrigger(t *testing.T) { // location is not defined herein but expected to be provided because, for // example, a CLI may want to use XDG_CONFIG_HOME. Assuming a repository path // $FAAS_TEMPLATES, a Go template named 'json' which is provided in the -// repository repository 'boson-experimental', would be expected to be in the -// location: +// repository 'boson-experimental', would be expected to be in the location: // $FAAS_TEMPLATES/boson-experimental/go/json // See the CLI for full details, but a standard default location is // $HOME/.config/templates/boson-experimental/go/json @@ -170,7 +169,7 @@ func TestExtensibleTemplates(t *testing.T) { // Create a new client with a path to the extensible templates client := faas.New( faas.WithTemplates("testdata/templates"), - faas.WithRepository(TestRepository)) + faas.WithRegistry(TestRegistry)) // Create a Function specifying a template, 'json' that only exists in the extensible set if err := client.Create(faas.Function{Root: root, Trigger: "boson-experimental/json"}); err != nil { @@ -243,7 +242,7 @@ func TestNamed(t *testing.T) { } defer os.RemoveAll(root) - client := faas.New(faas.WithRepository(TestRepository)) + client := faas.New(faas.WithRegistry(TestRegistry)) if err := client.Create(faas.Function{Root: root, Name: name}); err != nil { t.Fatal(err) @@ -259,19 +258,19 @@ func TestNamed(t *testing.T) { } } -// TestRepository ensures that a repository is required, and is +// TestRegistry ensures that a registry is required, and is // prepended with the DefaultRegistry if a single token. -// Repository is the namespace at the container image registry. +// Registry is the namespace at the container image registry. // If not prepended with the registry, it will be defaulted: // Examples: "docker.io/alice" // "quay.io/bob" // "charlie" (becomes [DefaultRegistry]/charlie -// At this time a repository namespace is required as we rely on a third-party +// At this time a registry namespace is required as we rely on a third-party // registry in all cases. When we support in-cluster container registries, // this configuration parameter will become optional. -func TestRepositoryRequired(t *testing.T) { +func TestRegistryRequired(t *testing.T) { // Create a root for the Function - root := "testdata/example.com/testRepository" + root := "testdata/example.com/testRegistry" if err := os.MkdirAll(root, 0700); err != nil { t.Fatal(err) } @@ -285,7 +284,7 @@ func TestRepositoryRequired(t *testing.T) { } // TestDeriveImage ensures that the full image (tag) of the resultant OCI -// container is populated based of a derivation using configured repository +// container is populated based of a derivation using configured registry // plus the service name. func TestDeriveImage(t *testing.T) { // Create the root Function directory @@ -296,7 +295,7 @@ func TestDeriveImage(t *testing.T) { defer os.RemoveAll(root) // Create the function which calculates fields such as name and image. - client := faas.New(faas.WithRepository(TestRepository)) + client := faas.New(faas.WithRegistry(TestRegistry)) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) } @@ -307,14 +306,14 @@ func TestDeriveImage(t *testing.T) { t.Fatal(err) } - // In form: [Default Registry]/[Repository Namespace]/[Service Name]:latest - expected := TestRepository + "/" + f.Name + ":latest" + // In form: [Default Registry]/[Registry Namespace]/[Service Name]:latest + expected := TestRegistry + "/" + f.Name + ":latest" if f.Image != expected { t.Fatalf("expected image '%v' got '%v'", expected, f.Image) } } -// TestDeriveImageDefaultRegistry ensures that a Repository which does not have +// TestDeriveImageDefaultRegistry ensures that a Registry which does not have // a registry prefix has the DefaultRegistry prepended. // For example "alice" becomes "docker.io/alice" func TestDeriveImageDefaultRegistry(t *testing.T) { @@ -326,9 +325,9 @@ func TestDeriveImageDefaultRegistry(t *testing.T) { defer os.RemoveAll(root) // Create the function which calculates fields such as name and image. - // Rather than use TestRepository, use a single-token name and expect + // Rather than use TestRegistry, use a single-token name and expect // the DefaultRegistry to be prepended. - client := faas.New(faas.WithRepository("alice")) + client := faas.New(faas.WithRegistry("alice")) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) } @@ -351,7 +350,7 @@ func TestDeriveImageDefaultRegistry(t *testing.T) { func TestCreateDelegates(t *testing.T) { var ( root = "testdata/example.com/testCreateDelegates" // .. in which to initialize - expectedName = "testCreateDelegates" // expected to be derived + expectedName = "testCreateDelegates" // expected to be derived expectedImage = "quay.io/alice/testCreateDelegates:latest" builder = mock.NewBuilder() pusher = mock.NewPusher() @@ -366,7 +365,7 @@ func TestCreateDelegates(t *testing.T) { // Create a client with mocks for each of the subcomponents. client := faas.New( - faas.WithRepository(TestRepository), + faas.WithRegistry(TestRegistry), faas.WithBuilder(builder), // builds an image faas.WithPusher(pusher), // pushes images to a registry faas.WithDeployer(deployer), // deploys images as a running service @@ -437,7 +436,7 @@ func TestRun(t *testing.T) { // Create a client with the mock runner and the new test Function runner := mock.NewRunner() - client := faas.New(faas.WithRepository(TestRepository), faas.WithRunner(runner)) + client := faas.New(faas.WithRegistry(TestRegistry), faas.WithRunner(runner)) if err := client.Create(faas.Function{Root: root}); err != nil { t.Fatal(err) } @@ -480,7 +479,7 @@ func TestUpdate(t *testing.T) { // A client with mocks whose implementaton will validate input. client := faas.New( - faas.WithRepository(TestRepository), + faas.WithRegistry(TestRegistry), faas.WithBuilder(builder), faas.WithPusher(pusher), faas.WithDeployer(deployer)) @@ -554,7 +553,7 @@ func TestRemoveByPath(t *testing.T) { defer os.RemoveAll(root) client := faas.New( - faas.WithRepository(TestRepository), + faas.WithRegistry(TestRegistry), faas.WithRemover(remover)) if err := client.Create(faas.Function{Root: root}); err != nil { @@ -593,7 +592,7 @@ func TestRemoveByName(t *testing.T) { defer os.RemoveAll(root) client := faas.New( - faas.WithRepository(TestRepository), + faas.WithRegistry(TestRegistry), faas.WithRemover(remover)) if err := client.Create(faas.Function{Root: root}); err != nil { @@ -644,7 +643,7 @@ func TestRemoveUninitializedFails(t *testing.T) { // Instantiate the client with the failing remover. client := faas.New( - faas.WithRepository(TestRepository), + faas.WithRegistry(TestRegistry), faas.WithRemover(remover)) // Attempt to remove by path (uninitialized), expecting an error. diff --git a/cmd/build.go b/cmd/build.go index 9b513b513..789866ad8 100644 --- a/cmd/build.go +++ b/cmd/build.go @@ -15,9 +15,9 @@ func init() { root.AddCommand(buildCmd) buildCmd.Flags().StringP("builder", "b", "default", "Buildpacks builder") buildCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FAAS_CONFIRM") - buildCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --repository) - $FAAS_IMAGE") + buildCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --registry) - $FAAS_IMAGE") buildCmd.Flags().StringP("path", "p", cwd(), "Path to the Function project directory - $FAAS_PATH") - buildCmd.Flags().StringP("repository", "r", "", "Repository for built images, ex 'docker.io/myuser' or just 'myuser'. Optional if --image provided. - $FAAS_REPOSITORY") + buildCmd.Flags().StringP("registry", "r", "", "Registry for built images, ex 'docker.io/myuser' or just 'myuser'. Optional if --image provided. - $FAAS_REGISTRY") err := buildCmd.RegisterFlagCompletionFunc("builder", CompleteBuilderList) if err != nil { @@ -32,12 +32,12 @@ var buildCmd = &cobra.Command{ Builds the Function project in the current directory or in the directory specified by the --path flag. The faas.yaml file is read to determine the -image name and repository. If both of these values are unset in the -configuration file the --repository or -r flag should be provided and an image +image name and registry. If both of these values are unset in the +configuration file the --registry or -r flag should be provided and an image name will be derived from the project name. -Any value provided for --image or --repository will be persisted in the -faas.yaml configuration file. On subsequent invocations of the "build" command +Any value provided for the --image flag will be persisted in the faas.yaml +configuration file. On subsequent invocations of the "build" command these values will be read from the configuration file. It's possible to use a custom Buildpack builder with the --builder flag. @@ -45,7 +45,7 @@ The value may be image name e.g. "cnbs/sample-builder:bionic", or reference to builderMaps in the config file e.g. "default". `, SuggestFor: []string{"biuld", "buidl", "built"}, - PreRunE: bindEnv("image", "path", "builder", "repository", "confirm"), + PreRunE: bindEnv("image", "path", "builder", "registry", "confirm"), RunE: runBuild, } @@ -57,12 +57,12 @@ func runBuild(cmd *cobra.Command, _ []string) (err error) { } // If the Function does not yet have an image name, and one was not provided - // on the command line AND a --repository was not provided, then we need to - // prompt for a repository from which we can derive an image name. - if function.Image == "" && config.Repository == "" { - fmt.Print("A repository for Function images is required. For example, 'docker.io/tigerteam'.\n\n") - config.Repository = prompt.ForString("Repository for Function images", "") - if config.Repository == "" { + // on the command line AND a --registry was not provided, then we need to + // prompt for a registry from which we can derive an image name. + if function.Image == "" && config.Registry == "" { + fmt.Print("A registry for Function images is required. For example, 'docker.io/tigerteam'.\n\n") + config.Registry = prompt.ForString("Registry for Function images", "") + if config.Registry == "" { return fmt.Errorf("Unable to determine Function image name") } } @@ -72,7 +72,7 @@ func runBuild(cmd *cobra.Command, _ []string) (err error) { client := faas.New( faas.WithVerbose(config.Verbose), - faas.WithRepository(config.Repository), // for deriving image name when --image not provided explicitly. + faas.WithRegistry(config.Registry), // for deriving image name when --image not provided explicitly. faas.WithBuilder(builder)) config.Prompt() @@ -82,21 +82,19 @@ func runBuild(cmd *cobra.Command, _ []string) (err error) { type buildConfig struct { // Image name in full, including registry, repo and tag (overrides - // image name derivation based on Repository and Function Name) + // image name derivation based on Registry and Function Name) Image string // Path of the Function implementation on local disk. Defaults to current // working directory of the process. Path string - // Push the resultnat image to the repository after building. + // Push the resulting image to the registry after building. Push bool - // Repository at which interstitial build artifacts should be kept. - // Registry is optional and is defaulted to faas.DefaultRegistry. - // ex: "quay.io/myrepo" or "myrepo" + // Registry at which interstitial build artifacts should be kept. // This setting is ignored if Image is specified, which includes the full - Repository string + Registry string // Verbose logging. Verbose bool @@ -109,12 +107,12 @@ type buildConfig struct { func newBuildConfig() buildConfig { return buildConfig{ - Image: viper.GetString("image"), - Path: viper.GetString("path"), - Repository: viper.GetString("repository"), - Verbose: viper.GetBool("verbose"), // defined on root - Confirm: viper.GetBool("confirm"), - Builder: viper.GetString("builder"), + Image: viper.GetString("image"), + Path: viper.GetString("path"), + Registry: viper.GetString("registry"), + Verbose: viper.GetBool("verbose"), // defined on root + Confirm: viper.GetBool("confirm"), + Builder: viper.GetString("builder"), } } @@ -122,7 +120,7 @@ func newBuildConfig() buildConfig { // Skipped if not in an interactive terminal (non-TTY), or if --confirm false (agree to // all prompts) was set (default). func (c buildConfig) Prompt() buildConfig { - imageName := deriveImage(c.Image, c.Repository, c.Path) + imageName := deriveImage(c.Image, c.Registry, c.Path) if !interactiveTerminal() || !c.Confirm { // If --confirm false or non-interactive, just print the image name fmt.Printf("Building image: %v\n", imageName) @@ -132,7 +130,7 @@ func (c buildConfig) Prompt() buildConfig { Path: prompt.ForString("Path to project directory", c.Path), Image: prompt.ForString("Image name", imageName, prompt.WithRequired(true)), Verbose: c.Verbose, - // Repository not prompted for as it would be confusing when combined with explicit image. Instead it is - // inferred by the derived default for Image, which uses Repository for derivation. + // Registry not prompted for as it would be confusing when combined with explicit image. Instead it is + // inferred by the derived default for Image, which uses Registry for derivation. } } diff --git a/cmd/create.go b/cmd/create.go index 77235268c..c00f8035d 100644 --- a/cmd/create.go +++ b/cmd/create.go @@ -18,9 +18,9 @@ import ( func init() { root.AddCommand(createCmd) createCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FAAS_CONFIRM") - createCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --repository) - $FAAS_IMAGE") + createCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --registry) - $FAAS_IMAGE") createCmd.Flags().StringP("namespace", "n", "", "Override namespace into which the Function is deployed (on supported platforms). Default is to use currently active underlying platform setting - $FAAS_NAMESPACE") - createCmd.Flags().StringP("repository", "r", "", "Repository for built images, ex 'docker.io/myuser' or just 'myuser'. Optional if --image provided. - $FAAS_REPOSITORY") + createCmd.Flags().StringP("registry", "r", "", "Registry for built images, ex 'docker.io/myuser' or just 'myuser'. Optional if --image provided. - $FAAS_REGISTRY") createCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. Default runtime is 'go'. Available runtimes: 'node', 'quarkus' and 'go'. - $FAAS_RUNTIME") createCmd.Flags().StringP("templates", "", filepath.Join(configPath(), "templates"), "Extensible templates path. - $FAAS_TEMPLATES") createCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger. Default trigger is 'http'. Available triggers: 'http' and 'events' - $FAAS_TRIGGER") @@ -46,16 +46,16 @@ created. The Function name is the name of the leaf directory at . After creating the project, a container image is created and is deployed. This command wraps "init", "build" and "deploy" all up into one command. -The runtime, trigger, image name, image repository, and namespace may all be +The runtime, trigger, image name, image registry, and namespace may all be specified as flags on the command line, and will subsequently be the default values when an image is built or a Function is deployed. If the image name and -image repository are both unspecified, the user will be prompted for a -repository name, and the image name can be inferred from that plus the function -name. The function name, namespace, image name and repository name are all -persisted in the project configuration file faas.yaml. +image registry are both unspecified, the user will be prompted for an image +registry, and the image name can be inferred from that plus the function +name. The function name, namespace and image name are all persisted in the +project configuration file faas.yaml. `, SuggestFor: []string{"cerate", "new"}, - PreRunE: bindEnv("image", "namespace", "repository", "runtime", "templates", "trigger", "confirm"), + PreRunE: bindEnv("image", "namespace", "registry", "runtime", "templates", "trigger", "confirm"), RunE: runCreate, } @@ -70,10 +70,10 @@ func runCreate(cmd *cobra.Command, args []string) (err error) { Image: config.Image, } - if function.Image == "" && config.Repository == "" { - fmt.Print("A repository for Function images is required. For example, 'docker.io/tigerteam'.\n\n") - config.Repository = prompt.ForString("Repository for Function images", "") - if config.Repository == "" { + if function.Image == "" && config.Registry == "" { + fmt.Print("A registry for Function images is required. For example, 'docker.io/tigerteam'.\n\n") + config.Registry = prompt.ForString("Registry for Function images", "") + if config.Registry == "" { return fmt.Errorf("Unable to determine Function image name") } } @@ -99,7 +99,7 @@ func runCreate(cmd *cobra.Command, args []string) (err error) { client := faas.New( faas.WithVerbose(verbose), faas.WithTemplates(config.Templates), - faas.WithRepository(config.Repository), // for deriving image name when --image not provided explicitly. + faas.WithRegistry(config.Registry), // for deriving image name when --image not provided explicitly. faas.WithBuilder(builder), faas.WithPusher(pusher), faas.WithDeployer(deployer), @@ -145,7 +145,7 @@ func (c createConfig) Prompt() createConfig { }, deployConfig: deployConfig{ buildConfig: buildConfig{ - Repository: prompt.ForString("Repository for Function images", c.buildConfig.Repository), + Registry: prompt.ForString("Registry for Function images", c.buildConfig.Registry), }, Namespace: prompt.ForString("Override default deploy namespace", c.Namespace), }, diff --git a/cmd/deploy.go b/cmd/deploy.go index c9724b410..1434a060a 100644 --- a/cmd/deploy.go +++ b/cmd/deploy.go @@ -17,10 +17,10 @@ import ( func init() { root.AddCommand(deployCmd) deployCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FAAS_CONFIRM") - deployCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --repository) - $FAAS_IMAGE") + deployCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --registry) - $FAAS_IMAGE") deployCmd.Flags().StringP("namespace", "n", "", "Override namespace into which the Function is deployed (on supported platforms). Default is to use currently active underlying platform setting - $FAAS_NAMESPACE") deployCmd.Flags().StringP("path", "p", cwd(), "Path to the function project directory - $FAAS_PATH") - deployCmd.Flags().StringP("repository", "r", "", "Repository for built images, ex 'docker.io/myuser' or just 'myuser'. - $FAAS_REPOSITORY") + deployCmd.Flags().StringP("registry", "r", "", "Image registry for built images, ex 'docker.io/myuser' or just 'myuser'. - $FAAS_REGISTRY") } var deployCmd = &cobra.Command{ @@ -31,11 +31,11 @@ var deployCmd = &cobra.Command{ Builds and Deploys the Function project in the current directory. A path to the project directory may be provided using the --path or -p flag. Reads the faas.yaml configuration file to determine the image name. -An image and repository may be specified on the command line using -the --image or -i and --repository or -r flag. +An image and registry may be specified on the command line using +the --image or -i and --registry or -r flag. If the Function is already deployed, it is updated with a new container image -that is pushed to an image repository, and the Knative Service is updated. +that is pushed to an image registry, and the Knative Service is updated. The namespace into which the project is deployed defaults to the value in the faas.yaml configuration file. If NAMESPACE is not set in the configuration, @@ -46,7 +46,7 @@ or -n flag, and if so this will overwrite the value in the faas.yaml file. `, SuggestFor: []string{"delpoy", "deplyo"}, - PreRunE: bindEnv("image", "namespace", "path", "repository", "confirm"), + PreRunE: bindEnv("image", "namespace", "path", "registry", "confirm"), RunE: runDeploy, } @@ -66,18 +66,18 @@ func runDeploy(cmd *cobra.Command, _ []string) (err error) { // If the Function does not yet have an image name and one was not provided on the command line if function.Image == "" { - // AND a --repository was not provided, then we need to - // prompt for a repository from which we can derive an image name. - if config.Repository == "" { - fmt.Print("A repository for Function images is required. For example, 'docker.io/tigerteam'.\n\n") - config.Repository = prompt.ForString("Repository for Function images", "") - if config.Repository == "" { + // AND a --registry was not provided, then we need to + // prompt for a registry from which we can derive an image name. + if config.Registry == "" { + fmt.Print("A registry for Function images is required. For example, 'docker.io/tigerteam'.\n\n") + config.Registry = prompt.ForString("Registry for Function images", "") + if config.Registry == "" { return fmt.Errorf("Unable to determine Function image name") } } - // We have the repository, so let's use it to derive the Function image name - config.Image = deriveImage(config.Image, config.Repository, config.Path) + // We have the registry, so let's use it to derive the Function image name + config.Image = deriveImage(config.Image, config.Registry, config.Path) function.Image = config.Image } @@ -105,7 +105,7 @@ func runDeploy(cmd *cobra.Command, _ []string) (err error) { client := faas.New( faas.WithVerbose(config.Verbose), - faas.WithRepository(config.Repository), // for deriving image name when --image not provided explicitly. + faas.WithRegistry(config.Registry), // for deriving image name when --image not provided explicitly. faas.WithBuilder(builder), faas.WithPusher(pusher), faas.WithDeployer(deployer), @@ -161,14 +161,14 @@ func (c deployConfig) Prompt() deployConfig { } dc := deployConfig{ buildConfig: buildConfig{ - Repository: prompt.ForString("Repository for Function images", c.buildConfig.Repository), + Registry: prompt.ForString("Registry for Function images", c.buildConfig.Registry), }, Namespace: prompt.ForString("Namespace", c.Namespace), Path: prompt.ForString("Project path", c.Path), Verbose: c.Verbose, } - dc.Image = deriveImage(dc.Image, dc.Repository, dc.Path) + dc.Image = deriveImage(dc.Image, dc.Registry, dc.Path) return dc } diff --git a/cmd/root.go b/cmd/root.go index da221e4cf..563d5dec0 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -195,7 +195,7 @@ func deriveNameAndAbsolutePathFromPath(path string) (string, string) { } // deriveImage returns the same image name which will be used if no explicit -// image is provided. I.e. derived from the configured repository (registry +// image is provided. I.e. derived from the configured registry (registry // plus username) and the Function's name. // // This is calculated preemptively here in the CLI (prior to invoking the @@ -214,9 +214,9 @@ func deriveNameAndAbsolutePathFromPath(path string) (string, string) { // If the image flag is provided, this value is used directly (the user supplied // --image or $FAAS_IMAGE). Otherwise, the Function at 'path' is loaded, and // the Image name therein is used (i.e. it was previously calculated). -// Finally, the default repository is used, which is prepended to the Function +// Finally, the default registry is used, which is prepended to the Function // name, and appended with ':latest': -func deriveImage(explicitImage, defaultRepo, path string) string { +func deriveImage(explicitImage, defaultRegistry, path string) string { if explicitImage != "" { return explicitImage // use the explicit value provided. } @@ -227,6 +227,6 @@ func deriveImage(explicitImage, defaultRepo, path string) string { if f.Image != "" { return f.Image // use value previously provided or derived. } - derivedValue, _ := faas.DerivedImage(path, defaultRepo) + derivedValue, _ := faas.DerivedImage(path, defaultRegistry) return derivedValue // Use the faas system's derivation logic. } diff --git a/docs/commands.md b/docs/commands.md index d56e609be..0e4bf5969 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,20 +18,20 @@ kn faas init [-l -t ] ## `build` -Builds the Function project in the current directory. Reads the `faas.yaml` file to determine image name and repository. If both of these values are unset in the configuration file, the user is prompted to provide a repository, from there an image name can be derived. The image name and repository may also be specified as flags, as can the path to the project. +Builds the Function project in the current directory. Reads the `faas.yaml` file to determine image name and registry. If both of these values are unset in the configuration file, the user is prompted to provide a registry, from there an image name can be derived. The image name and registry may also be specified as flags, as can the path to the project. -The value(s) provided for image and repository are persisted to the `faas.yaml` file so that subsequent invocations do not require the user to specify these again. +The value(s) provided for image and registry are persisted to the `faas.yaml` file so that subsequent invocations do not require the user to specify these again. Similar `kn` command: none. ```console -faas build [-i -r -p ] +faas build [-i -r -p ] ``` When run as a `kn` plugin. ```console -kn faas build [-i -r -p ] +kn faas build [-i -r -p ] ``` ## `run` @@ -52,25 +52,25 @@ kn faas run ## `deploy` -Builds and deploys the Function project in the current directory. The user may specify a path to the project directory using the `--path` or `-p` flag. Reads the `faas.yaml` configuration file to determine the image name. An image and repository may be specified on the command line using the `--image` or `-i` and `--repository` or `-r` flag. +Builds and deploys the Function project in the current directory. The user may specify a path to the project directory using the `--path` or `-p` flag. Reads the `faas.yaml` configuration file to determine the image name. An image and registry may be specified on the command line using the `--image` or `-i` and `--registry` or `-r` flag. Derives the service name from the project name. There is no mechanism by which the user can specify the service name. The user must have already initialized the function using `faas init` or they will encounter an error. If the Function is already deployed, it is updated with a new container image that is pushed to a -container image repository, and the Knative Service is updated. +container image registry, and the Knative Service is updated. The namespace into which the project is deployed defaults to the value in the `faas.yaml` configuration file. If `NAMESPACE` is not set in the configuration, the namespace currently active in the Kubernetes configuration file will be used. The namespace may be specified on the command line using the `--namespace` or `-n` flag, and if so this will overwrite the value in the `faas.yaml` file. Similar `kn` command: `kn service create NAME --image IMAGE [flags]`. This command allows a user to deploy a Knative Service by specifying an image, typically one hosted on a public container registry such as docker.io. The deployment options which the `kn` command affords the user are quite broad. The `kn` command in this case is quite effective for a power user. The `faas deploy` command has a similar end result, but is definitely easier for a user just getting started to be successful with. ```console -faas deploy [-n -p -i -r ] +faas deploy [-n -p -i -r ] ``` When run as a `kn` plugin. ```console -kn faas deploy [-n -p -i -r ] +kn faas deploy [-n -p -i -r ] ``` ## `describe` @@ -109,18 +109,18 @@ kn faas list [-n -p ] Creates a new Function project at _`path`_. If _`path`_ does not exist, it is created. The function name is the name of the leaf directory at _`path`_. After creating the project, it builds a container image and deploys it. This command wraps `init`, `build` and `deploy` all up into one command. -The user may specify the runtime, trigger, image name, image repository, and namespace as flags on the command line. If the image name and image repository are both unspecified, the user will be prompted for a repository name, and the image name can be inferred from that plus the function name. The function name, namespace, image name and repository name are all persisted in the project configuration file `faas.yaml`. +The user may specify the runtime, trigger, image name, image registry, and namespace as flags on the command line. If the image name and image registry are both unspecified, the user will be prompted for a registry name, and the image name can be inferred from that plus the function name. The function name, namespace and image name are all persisted in the project configuration file `faas.yaml`. Similar `kn` command: none. ```console -faas create -r -l -t -i -n +faas create -r -l -t -i -n ``` When run as a `kn` plugin. ```console -kn faas create -r -l -t -i -n +kn faas create -r -l -t -i -n ``` ## `delete` diff --git a/docs/integrators_guide.md b/docs/integrators_guide.md index cc6769ba5..6874b8bfa 100644 --- a/docs/integrators_guide.md +++ b/docs/integrators_guide.md @@ -4,7 +4,7 @@ Developer's can integrate directly with the Function system using the client lib ## Using the Client Library -To create a Client which uses the included buildpacks-based function builder, pushes to a Quay.io repository function container artifacts and deploys to a Knative enabled cluster: +To create a Client which uses the included buildpacks-based function builder, pushes to a Quay.io registry function container artifacts and deploys to a Knative enabled cluster: ```go package main diff --git a/function.go b/function.go index 7df37fd43..984f38384 100644 --- a/function.go +++ b/function.go @@ -26,9 +26,9 @@ type Function struct { // Trigger of the Function. http|events etc. Trigger string - // Repository at which to store interstitial containers, in the form + // Registry at which to store interstitial containers, in the form // [registry]/[user]. If omitted, "Image" must be provided. - Repo string + Registry string // Optional full OCI image tag in form: // [registry]/[namespace]/[name]:[tag] @@ -38,7 +38,7 @@ type Function struct { // example: // alice/my.function.name // If Image is provided, it overrides the default of concatenating - // "Repo+Name:latest" to derive the Image. + // "Registry+Name:latest" to derive the Image. Image string // Builder represents the CNCF Buildpack builder image for a function, @@ -99,18 +99,17 @@ func (f Function) Initialized() bool { } // DerivedImage returns the derived image name (OCI container tag) of the -// Function whose source is at root, with the default repository for when +// Function whose source is at root, with the default registry for when // the image has to be calculated (derived). -// repository can be either with or without prefixed registry. // The following are eqivalent due to the use of DefaultRegistry: -// repository: docker.io/myname -// myname -// A full image name consists of registry, repository, name and tag. -// in form [registry]/[repository]/[name]:[tag] +// registry: docker.io/myname +// myname +// A full image name consists of registry, image name and tag. +// in form [registry]/[image-name]:[tag] // example docker.io/alice/my.example.func:latest -// Default if not provided is --repository (a required global setting) +// Default if not provided is --registry (a required global setting) // followed by the provided (or derived) image name. -func DerivedImage(root, repository string) (image string, err error) { +func DerivedImage(root, registry string) (image string, err error) { f, err := NewFunction(root) if err != nil { // an inability to load the Function means it is not yet initialized @@ -127,26 +126,26 @@ func DerivedImage(root, repository string) (image string, err error) { return } - // Repository is currently required until such time as we support + // registry is currently required until such time as we support // pushing to an implicitly-available in-cluster registry by default. - if repository == "" { - err = errors.New("Repository name is required.") + if registry == "" { + err = errors.New("Registry name is required.") return } // If the Function loaded, and there is not yet an Image set, then this is // the first build and no explicit image override was specified. We should - // therefore derive the image tag from the defined repository and name. + // therefore derive the image tag from the defined registry and name. // form: [registry]/[user]/[function]:latest // example: quay.io/alice/my.function.name:latest - repository = strings.Trim(repository, "/") // too defensive? - repositoryTokens := strings.Split(repository, "/") - if len(repositoryTokens) == 1 { - image = DefaultRegistry + "/" + repository + "/" + f.Name - } else if len(repositoryTokens) == 2 { - image = repository + "/" + f.Name + registry = strings.Trim(registry, "/") // too defensive? + registryTokens := strings.Split(registry, "/") + if len(registryTokens) == 1 { + image = DefaultRegistry + "/" + registry + "/" + f.Name + } else if len(registryTokens) == 2 { + image = registry + "/" + f.Name } else { - err = fmt.Errorf("repository should be either 'namespace' or 'registry/namespace'") + err = fmt.Errorf("registry should be either 'namespace' or 'registry/namespace'") } // Explicitly append :latest. We currently expect source control to drive diff --git a/templates.go b/templates.go index dd3b094e2..ad249ef8f 100644 --- a/templates.go +++ b/templates.go @@ -61,7 +61,7 @@ func (n templateWriter) Write(runtime, template string, dest string) error { if n.templates != "" { return copyFilesystem(n.templates, runtime, template, dest) } - return fmt.Errorf("A template for runtime '%v' template '%v' was not found internally and no extended repository path was defined.", runtime, template) + return fmt.Errorf("A template for runtime '%v' template '%v' was not found internally and no custom template path was defined.", runtime, template) } func copyEmbedded(runtime, template, dest string) error {