diff --git a/cmd/operator-sdk/cli/cli.go b/cmd/operator-sdk/cli/cli.go index 0833bc118c..2144e474ec 100644 --- a/cmd/operator-sdk/cli/cli.go +++ b/cmd/operator-sdk/cli/cli.go @@ -20,6 +20,7 @@ import ( "github.com/operator-framework/operator-sdk/cmd/operator-sdk/bundle" "github.com/operator-framework/operator-sdk/cmd/operator-sdk/completion" "github.com/operator-framework/operator-sdk/cmd/operator-sdk/generate" + "github.com/operator-framework/operator-sdk/cmd/operator-sdk/new" "github.com/operator-framework/operator-sdk/cmd/operator-sdk/olm" "github.com/operator-framework/operator-sdk/cmd/operator-sdk/version" "github.com/operator-framework/operator-sdk/internal/flags" @@ -33,9 +34,9 @@ import ( ) var commands = []*cobra.Command{ - // Once the KB CLI is made the default, add the "new" command as a way to - // scaffold the legacy project layout and mark "new" as deprecated - // new.NewCmd() + // The "new" cmd provides a way to scaffold Helm/Ansible projects + // from the new CLI. + new.NewCmd(), alpha.NewCmd(), build.NewCmd(), diff --git a/cmd/operator-sdk/main.go b/cmd/operator-sdk/main.go index 6bf195ba01..6fa697c89a 100644 --- a/cmd/operator-sdk/main.go +++ b/cmd/operator-sdk/main.go @@ -15,7 +15,6 @@ package main import ( - "os" // Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.) // to ensure that `exec-entrypoint` and `run` can make use of them. @@ -23,16 +22,13 @@ import ( "github.com/operator-framework/operator-sdk/cmd/operator-sdk/cli" kbutil "github.com/operator-framework/operator-sdk/internal/util/kubebuilder" + "github.com/operator-framework/operator-sdk/internal/util/projutil" log "github.com/sirupsen/logrus" ) func main() { - // Use the new KB CLI only when running inside an existing Kubebuilder project with a PROJECT file. - // The default legacy CLI provides the init cmd to initialize - // a Kubebuilder project as a way to opt into the new KB CLI. - // TODO: Make the new KB CLI the default, once the integration is complete - // and deprecate "operator-sdk new" from the old CLI. + // Use the new KB CLI when running inside a Kubebuilder project with an existing PROJECT file. if kbutil.HasProjectFile() { if err := cli.Run(); err != nil { log.Fatal(err) @@ -40,7 +36,30 @@ func main() { return } - if err := cli.RunLegacy(); err != nil { - os.Exit(1) + // Use the legacy CLI if inside of a Go/Helm/Ansible legacy project + operatorType := projutil.GetOperatorType() + switch operatorType { + case projutil.OperatorTypeGo, projutil.OperatorTypeHelm, projutil.OperatorTypeAnsible: + // Deprecation warning for Go projects + // TODO/Discuss: UX wise, is displaying this notice on every command that runs + // in the legacy Go projects too loud. + if operatorType == projutil.OperatorTypeGo { + depMsg := "Operator SDK has a new CLI and project layout that is aligned with Kubebuilder.\n" + + "See `operator-sdk init -h` and the following doc on how to scaffold a new project:\n" + + "https://sdk.operatorframework.io/docs/golang/new/quickstart/\n" + + "To migrate existing projects to the new layout see:\n" + + "https://sdk.operatorframework.io/docs/golang/new/migration/project_migration_guide/\n" + projutil.PrintDeprecationWarning(depMsg) + } + if err := cli.RunLegacy(); err != nil { + log.Fatal(err) + } + return + } + + // Run the KB CLI when not running in either legacy or new projects + // The new CLI still supports "operator-sdk new --type=Ansible/Helm" + if err := cli.Run(); err != nil { + log.Fatal(err) } } diff --git a/cmd/operator-sdk/new/cmd.go b/cmd/operator-sdk/new/cmd.go index 64a1183098..3e40944aac 100644 --- a/cmd/operator-sdk/new/cmd.go +++ b/cmd/operator-sdk/new/cmd.go @@ -18,7 +18,6 @@ import ( "fmt" "os" "os/exec" - "path" "path/filepath" "strings" @@ -53,9 +52,6 @@ generates a default directory layout based on the input . $ mkdir $HOME/projects/example.com/ $ cd $HOME/projects/example.com/ - # Go project - $ operator-sdk new app-operator - # Ansible project $ operator-sdk new app-operator --type=ansible \ --api-version=app.example.com/v1alpha1 \ @@ -95,18 +91,14 @@ generates a default directory layout based on the input . `, RunE: newFunc, } - newCmd.Flags().StringVar(&operatorType, "type", "go", - "Type of operator to initialize (choices: \"go\", \"ansible\" or \"helm\")") - newCmd.Flags().StringVar(&repo, "repo", "", - "Project repository path for Go operators. Used as the project's Go import path. This must be set if "+ - "outside of $GOPATH/src (e.g. github.com/example-inc/my-operator)") + + newCmd.Flags().StringVar(&operatorType, "type", "", + "Type of operator to initialize (choices: \"ansible\" or \"helm\")") + if err := newCmd.MarkFlagRequired("type"); err != nil { + log.Fatalf("Failed to mark `type` flag for `new` subcommand as required") + } newCmd.Flags().BoolVar(&gitInit, "git-init", false, "Initialize the project directory as a git repository (default false)") - newCmd.Flags().StringVar(&headerFile, "header-file", "", - "Path to file containing headers for generated Go files. Copied to hack/boilerplate.go.txt") - newCmd.Flags().BoolVar(&makeVendor, "vendor", false, "Use a vendor directory for dependencies") - newCmd.Flags().BoolVar(&skipValidation, "skip-validation", false, - "Do not validate the resulting project's structure and dependencies. (Only used for --type go)") newCmd.Flags().BoolVar(&generatePlaybook, "generate-playbook", false, "Generate a playbook skeleton. (Only used for --type ansible)") @@ -120,11 +112,7 @@ var ( apiFlags apiflags.APIFlags operatorType string projectName string - headerFile string - repo string gitInit bool - makeVendor bool - skipValidation bool generatePlaybook bool ) @@ -140,22 +128,6 @@ func newFunc(cmd *cobra.Command, args []string) error { log.Infof("Creating new %s operator '%s'.", strings.Title(operatorType), projectName) switch operatorType { - case projutil.OperatorTypeGo: - if repo == "" { - repo = path.Join(projutil.GetGoPkg(), projectName) - } - if err := doGoScaffold(); err != nil { - log.Fatal(err) - } - if err := getDeps(); err != nil { - log.Fatal(err) - } - if !skipValidation { - if err := validateProject(); err != nil { - log.Fatal(err) - } - } - case projutil.OperatorTypeAnsible: if err := doAnsibleScaffold(); err != nil { log.Fatal(err) @@ -229,48 +201,6 @@ func mustBeNewProject() { } } -func doGoScaffold() error { - cfg := &input.Config{ - Repo: repo, - AbsProjectPath: filepath.Join(projutil.MustGetwd(), projectName), - ProjectName: projectName, - } - s := &scaffold.Scaffold{} - - if headerFile != "" { - err := s.Execute(cfg, &scaffold.Boilerplate{BoilerplateSrcPath: headerFile}) - if err != nil { - return fmt.Errorf("boilerplate scaffold failed: %v", err) - } - s.BoilerplatePath = headerFile - } - - if err := projutil.CheckGoModules(); err != nil { - return err - } - - err := s.Execute(cfg, - &scaffold.GoMod{}, - &scaffold.Tools{}, - &scaffold.Cmd{}, - &scaffold.Dockerfile{}, - &scaffold.Entrypoint{}, - &scaffold.UserSetup{}, - &scaffold.ServiceAccount{}, - &scaffold.Role{}, - &scaffold.RoleBinding{}, - &scaffold.Operator{}, - &scaffold.Apis{}, - &scaffold.Controller{}, - &scaffold.Version{}, - &scaffold.Gitignore{}, - ) - if err != nil { - return fmt.Errorf("new Go scaffold failed: %v", err) - } - return nil -} - func doAnsibleScaffold() error { cfg := &input.Config{ AbsProjectPath: filepath.Join(projutil.MustGetwd(), projectName), @@ -365,23 +295,13 @@ func doAnsibleScaffold() error { } func verifyFlags() error { - if operatorType != projutil.OperatorTypeGo && operatorType != projutil.OperatorTypeAnsible && operatorType != - projutil.OperatorTypeHelm { - return fmt.Errorf("value of --type can only be `go`, `ansible`, or `helm`: %v", + if operatorType != projutil.OperatorTypeAnsible && operatorType != projutil.OperatorTypeHelm { + return fmt.Errorf("value of --type can only be `ansible`, or `helm`: %v", projutil.ErrUnknownOperatorType{Type: operatorType}) } if operatorType != projutil.OperatorTypeAnsible && generatePlaybook { return fmt.Errorf("value of --generate-playbook can only be used with --type `ansible`") } - if operatorType == projutil.OperatorTypeGo { - if len(apiFlags.APIVersion) != 0 || len(apiFlags.Kind) != 0 { - return fmt.Errorf("operators of type Go do not use --api-version or --kind") - } - - if err := projutil.CheckRepo(repo); err != nil { - return err - } - } if err := apiFlags.VerifyCommonFlags(operatorType); err != nil { return err } @@ -395,26 +315,6 @@ func execProjCmd(cmd string, args ...string) error { return projutil.ExecCmd(dc) } -func getDeps() error { - - // Only when a user requests a vendor directory be created should - // "go mod vendor" be run during project initialization. - if !makeVendor { - return nil - } - - log.Info("Running go mod vendor") - opts := projutil.GoCmdOptions{ - Args: []string{"-v"}, - Dir: filepath.Join(projutil.MustGetwd(), projectName), - } - if err := projutil.GoCmd("mod vendor", opts); err != nil { - return err - } - log.Info("Done getting dependencies") - return nil -} - func initGit() error { log.Info("Running git init") if err := execProjCmd("git", "init"); err != nil { @@ -423,22 +323,3 @@ func initGit() error { log.Info("Run git init done") return nil } - -func validateProject() error { - log.Info("Validating project") - // Run "go build ./..." to make sure all packages can be built - // correctly. From "go help build": - // - // When compiling multiple packages or a single non-main package, - // build compiles the packages but discards the resulting object, - // serving only as a check that the packages can be built. - opts := projutil.GoCmdOptions{ - PackagePath: "./...", - Dir: filepath.Join(projutil.MustGetwd(), projectName), - } - if err := projutil.GoBuild(opts); err != nil { - return err - } - log.Info("Project validation successful.") - return nil -} diff --git a/hack/generate/cli-doc/gen-cli-doc.go b/hack/generate/cli-doc/gen-cli-doc.go index b3e33a443a..fafb1cbd32 100644 --- a/hack/generate/cli-doc/gen-cli-doc.go +++ b/hack/generate/cli-doc/gen-cli-doc.go @@ -22,6 +22,7 @@ import ( "strings" log "github.com/sirupsen/logrus" + "github.com/spf13/cobra" "github.com/spf13/cobra/doc" "github.com/operator-framework/operator-sdk/cmd/operator-sdk/cli" @@ -33,30 +34,31 @@ title: "%s" ` func main() { - // TODO: Generate CLI docs for plugins CLI at doc/cli/kubebuilder - root := cli.GetCLIRoot() - root.DisableAutoGenTag = true - - filePrepender := func(filename string) string { - name := filepath.Base(filename) - base := strings.TrimSuffix(name, path.Ext(name)) - return fmt.Sprintf(fmTemplate, strings.Replace(base, "_", " ", -1)) - } - linkHandler := func(name string) string { - base := strings.TrimSuffix(name, path.Ext(name)) - return "../" + base + currentDir, err := os.Getwd() + if err != nil { + log.Fatalf("Failed to get current directory: %v", err) } + legacyDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "cli") + legacyRoot := cli.GetCLIRoot() + legacyRoot.DisableAutoGenTag = true + recreateDocDir(legacyRoot, legacyDocPath) + + newDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "new-cli") + _, newRoot := cli.GetPluginsCLIAndRoot() + newRoot.DisableAutoGenTag = true + recreateDocDir(newRoot, newDocPath) +} + +// recreateDocDir removes and recreates the CLI doc directory for rootCmd +// at docPath to ensure that stale files (e.g. from renamed or removed CLI subcommands) +// are removed. +func recreateDocDir(rootCmd *cobra.Command, docPath string) { currentDir, err := os.Getwd() if err != nil { log.Fatalf("Failed to get current directory: %v", err) } - docPath := filepath.Join(currentDir, "website", "content", "en", "docs", "cli") - - // Remove and recreate the CLI doc directory to ensure that - // stale files (e.g. from renamed or removed CLI subcommands) - // are removed. if err := os.Rename(docPath+"/_index.md", currentDir+"/tmp_index.md"); err != nil { log.Fatalf("Failed to move existing index: %v", err) } @@ -67,7 +69,17 @@ func main() { log.Fatalf("Failed to re-create docs directory: %v", err) } - err = doc.GenMarkdownTreeCustom(root, docPath, filePrepender, linkHandler) + filePrepender := func(filename string) string { + name := filepath.Base(filename) + base := strings.TrimSuffix(name, path.Ext(name)) + return fmt.Sprintf(fmTemplate, strings.Replace(base, "_", " ", -1)) + } + linkHandler := func(name string) string { + base := strings.TrimSuffix(name, path.Ext(name)) + return "../" + base + } + + err = doc.GenMarkdownTreeCustom(rootCmd, docPath, filePrepender, linkHandler) if err != nil { log.Fatalf("Failed to generate documentation: %v", err) } diff --git a/hack/tests/scaffolding/e2e-go-scaffold.sh b/hack/tests/scaffolding/e2e-go-scaffold.sh index 26184758de..c0286c2af4 100755 --- a/hack/tests/scaffolding/e2e-go-scaffold.sh +++ b/hack/tests/scaffolding/e2e-go-scaffold.sh @@ -4,6 +4,24 @@ set -ex source hack/lib/test_lib.sh +function download_old_sdk_binary() { + VERSION="v0.18.1" + echo "Getting SDK $VERSION release binary..." + BIN_URL="" + OS=$(go env GOOS) + if [ "$OS" = "darwin" ]; then + BIN_URL="https://github.com/operator-framework/operator-sdk/releases/download/$VERSION/operator-sdk-$VERSION-x86_64-apple-darwin" + elif [ "$OS" = "linux" ]; then + BIN_URL="https://github.com/operator-framework/operator-sdk/releases/download/$VERSION/operator-sdk-$VERSION-x86_64-linux-gnu" + else + echo "Failed to get SDK $VERSION release binary for $OS" + exit 1 + fi + + curl -o operator-sdk-old -L $BIN_URL + chmod +x ./operator-sdk-old +} + ROOTDIR="$(pwd)" BASEPROJECTDIR="$(mktemp -d)" IMAGE_NAME="quay.io/example/memcached-operator:v0.0.1" @@ -34,5 +52,8 @@ set -- "${ORIG_ARGS[@]}" go build -o $BASEPROJECTDIR/scaffold-memcached $ROOTDIR/hack/tests/scaffolding/scaffold-memcached.go pushd "$BASEPROJECTDIR" +# scaffold-memcached uses "operator-sdk-old new ..." to scaffold the legacy project +# since "new" is not present in the new CLI +download_old_sdk_binary ./scaffold-memcached --local-repo $ROOTDIR --image-name=$IMAGE_NAME --local-image $@ popd diff --git a/hack/tests/scaffolding/scaffold-memcached.go b/hack/tests/scaffolding/scaffold-memcached.go index 557263d11d..0214e30807 100644 --- a/hack/tests/scaffolding/scaffold-memcached.go +++ b/hack/tests/scaffolding/scaffold-memcached.go @@ -59,8 +59,11 @@ func main() { localSDKPath = sdkTestE2EDir } + // Post v0.18.1 "operator-sdk new" is not part of the new CLI + // so we use an older release binary that should already be present locally + // from hack/tests/scaffolding/e2e-go-scaffold.sh log.Print("Creating new operator project") - cmdOut, err := exec.Command("operator-sdk", + cmdOut, err := exec.Command("./operator-sdk-old", "new", operatorName, "--repo", testRepo, diff --git a/internal/util/projutil/project_util.go b/internal/util/projutil/project_util.go index 8625f94543..66897d69e9 100644 --- a/internal/util/projutil/project_util.go +++ b/internal/util/projutil/project_util.go @@ -196,6 +196,7 @@ func parseGoPkg(gopath string) string { // This function should be called after verifying the user is in project root. func GetOperatorType() OperatorType { switch { + // TODO: Differentiate between legacy and KB Go projects case IsOperatorGo(): return OperatorTypeGo case IsOperatorAnsible(): @@ -314,15 +315,14 @@ func CheckGoModules() error { } if !goModOn { return fmt.Errorf(`using go modules requires GO111MODULE="on", "auto", or unset.` + - ` More info: https://sdk.operatorframework.io/docs/golang/quickstart/#a-note-on-dependency-management`) + ` More info: https://sdk.operatorframework.io/docs/golang/new/quickstart/#a-note-on-dependency-management`) } return nil } // PrintDeprecationWarning prints a colored warning wrapping msg to the terminal. func PrintDeprecationWarning(msg string) { - fmt.Printf(noticeColor, "[Deprecation Notice] "+msg+". Refer to the version upgrade guide "+ - "for more information: https://sdk.operatorframework.io/docs/migration/version-upgrade-guide/\n\n") + fmt.Fprintf(os.Stderr, noticeColor, "[Deprecation Notice] "+msg+"\n") } // RewriteFileContents adds the provided content before the last occurrence of the word label diff --git a/proposals/leader-for-life.md b/proposals/leader-for-life.md index cfe2bcce96..1e6b7871c3 100644 --- a/proposals/leader-for-life.md +++ b/proposals/leader-for-life.md @@ -4,7 +4,7 @@ Implementation Owner: > Status: **implemented** > -> See [leader election documentation](https://sdk.operatorframework.io/docs/golang/quickstart/#leader-election). +> See [leader election documentation](https://sdk.operatorframework.io/docs/golang/new/advanced-topics/#leader-election). - [Background](#background) - [Goals](#goals) diff --git a/proposals/metering-operator-metrics.md b/proposals/metering-operator-metrics.md index 000000d181..f9a6836be3 100644 --- a/proposals/metering-operator-metrics.md +++ b/proposals/metering-operator-metrics.md @@ -4,7 +4,7 @@ Implementation Owner: > Status: **implemented** > -> See [metrics documentation](https://sdk.operatorframework.io/docs/golang/monitoring/). +> See [metrics documentation](https://sdk.operatorframework.io/docs/golang/legacy/monitoring/). - [Motivation and goal](#motivation-and-goal) - [Overview of the metrics](#overview-of-the-metrics) diff --git a/proposals/qa-samples-proposal.md b/proposals/qa-samples-proposal.md index 6a7b7de4f7..a14538af38 100644 --- a/proposals/qa-samples-proposal.md +++ b/proposals/qa-samples-proposal.md @@ -134,4 +134,4 @@ The Operator SDK has a repo with [sample projects](https://github.com/operator-f [Coveralls](https://coveralls.io/) may not work well with [molecule](https://github.com/operator-framework/operator-sdk-samples/tree/master/ansible/memcached-operator/molecule), if this is the case we can just not integrate with it or we can find a similar tool. [operator-sdk-doc]: https://sdk.operatorframework.io/ -[e2e-docs]: https://sdk.operatorframework.io/docs/golang/e2e-tests/ +[e2e-docs]: https://sdk.operatorframework.io/docs/golang/legacy/e2e-tests/ diff --git a/website/content/en/build/_index.html b/website/content/en/build/_index.html index c83869c3e2..5e3b198a65 100644 --- a/website/content/en/build/_index.html +++ b/website/content/en/build/_index.html @@ -56,7 +56,7 @@

READ THE USER GUIDES

-
  • +
  • Go Quickstart diff --git a/website/content/en/docs/_index.md b/website/content/en/docs/_index.md index 6151a494a6..47c3c6272a 100644 --- a/website/content/en/docs/_index.md +++ b/website/content/en/docs/_index.md @@ -85,7 +85,7 @@ Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file f [controller_runtime]: https://github.com/kubernetes-sigs/controller-runtime [faq]: /docs/faq/ [getting_started]: https://github.com/operator-framework/getting-started/blob/master/README.md -[golang-guide]: /docs/golang/quickstart/ +[golang-guide]:/docs/golang/new/quickstart/ [helm-guide]:/docs/helm/quickstart/ [install_guide]: /docs/install-operator-sdk/ [license_file]:https://github.com/operator-framework/operator-sdk/blob/master/LICENSE diff --git a/website/content/en/docs/ansible/quickstart.md b/website/content/en/docs/ansible/quickstart.md index c8e59e2b95..ba494c7043 100644 --- a/website/content/en/docs/ansible/quickstart.md +++ b/website/content/en/docs/ansible/quickstart.md @@ -367,7 +367,7 @@ For more information, refer [cli][addcli] doc. [ansible-runner-http-plugin]:https://github.com/ansible/ansible-runner-http [ansible-runner-tool]: https://ansible-runner.readthedocs.io/en/latest/install.html [ansible-watches]: /docs/ansible/reference/watches -[operator-scope]:../../operator-scope +[operator-scope]:../../legacy-common/operator-scope [layout-doc]:../reference/scaffolding [homebrew-tool]:https://brew.sh/ [install-guide]: /docs/install-operator-sdk diff --git a/website/content/en/docs/cli/_index.md b/website/content/en/docs/cli/_index.md index 34ed891cbe..1cd6565755 100644 --- a/website/content/en/docs/cli/_index.md +++ b/website/content/en/docs/cli/_index.md @@ -1,4 +1,17 @@ --- -title: CLI Reference -weight: 30 +title: Ansible/Helm CLI Reference +weight: 31 --- + +**Note:** For Golang Operators this CLI has been deprecated. Please consult the [new CLI reference][new_CLI] doc. + +[new_CLI]:/docs/new-cli + + diff --git a/website/content/en/docs/cli/operator-sdk_new.md b/website/content/en/docs/cli/operator-sdk_new.md index 43e7d51749..aa711e4c01 100644 --- a/website/content/en/docs/cli/operator-sdk_new.md +++ b/website/content/en/docs/cli/operator-sdk_new.md @@ -24,9 +24,6 @@ operator-sdk new [flags] $ mkdir $HOME/projects/example.com/ $ cd $HOME/projects/example.com/ - # Go project - $ operator-sdk new app-operator - # Ansible project $ operator-sdk new app-operator --type=ansible \ --api-version=app.example.com/v1alpha1 \ @@ -73,17 +70,13 @@ operator-sdk new [flags] --crd-version string CRD version to generate (default "v1") --generate-playbook Generate a playbook skeleton. (Only used for --type ansible) --git-init Initialize the project directory as a git repository (default false) - --header-file string Path to file containing headers for generated Go files. Copied to hack/boilerplate.go.txt --helm-chart string Initialize helm operator with existing helm chart (, /, or local path). Valid only for --type helm --helm-chart-repo string Chart repository URL for the requested helm chart, Valid only for --type helm --helm-chart-version string Specific version of the helm chart (default is latest version). Valid only for --type helm -h, --help help for new --kind string Kubernetes resource Kind name. (e.g AppService) - --repo string Project repository path for Go operators. Used as the project's Go import path. This must be set if outside of $GOPATH/src (e.g. github.com/example-inc/my-operator) --skip-generation Skip generation of deepcopy and OpenAPI code and OpenAPI CRD specs - --skip-validation Do not validate the resulting project's structure and dependencies. (Only used for --type go) - --type string Type of operator to initialize (choices: "go", "ansible" or "helm") (default "go") - --vendor Use a vendor directory for dependencies + --type string Type of operator to initialize (choices: "ansible" or "helm") ``` ### SEE ALSO diff --git a/website/content/en/docs/contribution-guidelines/_index.md b/website/content/en/docs/contribution-guidelines/_index.md index 5dcb7d4dee..d51a56d17c 100644 --- a/website/content/en/docs/contribution-guidelines/_index.md +++ b/website/content/en/docs/contribution-guidelines/_index.md @@ -1,6 +1,6 @@ --- title: How to Contribute linkTitle: Contribution Guidelines -weight: 30 +weight: 40 --- diff --git a/website/content/en/docs/contribution-guidelines/testing/travis-build.md b/website/content/en/docs/contribution-guidelines/testing/travis-build.md index 4d696236e5..ae4d7a7ca3 100644 --- a/website/content/en/docs/contribution-guidelines/testing/travis-build.md +++ b/website/content/en/docs/contribution-guidelines/testing/travis-build.md @@ -115,4 +115,4 @@ The Go, Ansible, and Helm tests then differ in what tests they run. [ansible-test]: https://github.com/operator-framework/operator-sdk/tree/master/test/ansible [helm-e2e]: https://github.com/operator-framework/operator-sdk/blob/master/hack/tests/e2e-helm.sh [helm-base]: https://github.com/operator-framework/operator-sdk/blob/master/hack/image/helm/scaffold-helm-image.go -[deps_mgmt]: ../../../golang/quickstart#a-note-on-dependency-management +[deps_mgmt]: ../../../golang/new/quickstart#a-note-on-dependency-management diff --git a/website/content/en/docs/faq.md b/website/content/en/docs/faq.md index ca4e5b33b5..c5f7698223 100644 --- a/website/content/en/docs/faq.md +++ b/website/content/en/docs/faq.md @@ -144,8 +144,8 @@ This will work for the current environment. To persist this fix, add the above l [kube-apiserver_options]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/#options [controller-runtime_faq]: https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ.md#q-how-do-i-have-different-logic-in-my-reconciler-for-different-types-of-events-eg-create-update-delete -[finalizer]: /docs/golang/quickstart/#handle-cleanup-on-deletion -[gc-metrics]:/docs/golang/monitoring/prometheus/#garbage-collection +[finalizer]:/docs/golang/new/advanced-topics/#handle-cleanup-on-deletion +[gc-metrics]:/docs/golang/legacy/monitoring/prometheus/#garbage-collection [cr-faq]:https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ.md [client.Reader]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#Reader [rbac]:https://kubernetes.io/docs/reference/access-authn-authz/rbac/ diff --git a/website/content/en/docs/golang/legacy/_index.md b/website/content/en/docs/golang/legacy/_index.md new file mode 100644 index 0000000000..f0bdd690eb --- /dev/null +++ b/website/content/en/docs/golang/legacy/_index.md @@ -0,0 +1,4 @@ +--- +title: Golang Based Operators - Legacy CLI +weight: 200 +--- diff --git a/website/content/en/docs/golang/e2e-tests.md b/website/content/en/docs/golang/legacy/e2e-tests.md similarity index 99% rename from website/content/en/docs/golang/e2e-tests.md rename to website/content/en/docs/golang/legacy/e2e-tests.md index 5a83e60dfe..e444968559 100644 --- a/website/content/en/docs/golang/e2e-tests.md +++ b/website/content/en/docs/golang/legacy/e2e-tests.md @@ -383,6 +383,6 @@ $ kubectl delete -f deploy/crds/cache.example.com_memcacheds_crd.yaml [e2eutil-link]:https://github.com/operator-framework/operator-sdk/tree/master/pkg/test/e2eutil [memcached-test-link]:https://github.com/operator-framework/operator-sdk-samples/blob/master/go/memcached-operator/test/e2e/memcached_test.go [scheme-link]:https://github.com/operator-framework/operator-sdk/blob/v0.17.0/pkg/test/framework.go#L176 -[cli-test-local]: ../../cli/operator-sdk_test_local +[cli-test-local]: /docs/cli/operator-sdk_test_local [main-entry-link]:https://github.com/operator-framework/operator-sdk/blob/v0.17.0/pkg/test/main_entry.go#L25 [memcached-role]:https://github.com/operator-framework/operator-sdk-samples/blob/master/go/memcached-operator/deploy/role.yaml diff --git a/website/content/en/docs/golang/migrating-existing-apis.md b/website/content/en/docs/golang/legacy/migrating-existing-apis.md similarity index 100% rename from website/content/en/docs/golang/migrating-existing-apis.md rename to website/content/en/docs/golang/legacy/migrating-existing-apis.md diff --git a/website/content/en/docs/golang/monitoring/_index.md b/website/content/en/docs/golang/legacy/monitoring/_index.md similarity index 100% rename from website/content/en/docs/golang/monitoring/_index.md rename to website/content/en/docs/golang/legacy/monitoring/_index.md diff --git a/website/content/en/docs/golang/monitoring/prometheus.md b/website/content/en/docs/golang/legacy/monitoring/prometheus.md similarity index 100% rename from website/content/en/docs/golang/monitoring/prometheus.md rename to website/content/en/docs/golang/legacy/monitoring/prometheus.md diff --git a/website/content/en/docs/golang/monitoring/service-monitor.md b/website/content/en/docs/golang/legacy/monitoring/service-monitor.md similarity index 100% rename from website/content/en/docs/golang/monitoring/service-monitor.md rename to website/content/en/docs/golang/legacy/monitoring/service-monitor.md diff --git a/website/content/en/docs/golang/quickstart.md b/website/content/en/docs/golang/legacy/quickstart.md similarity index 98% rename from website/content/en/docs/golang/quickstart.md rename to website/content/en/docs/golang/legacy/quickstart.md index d865a56398..7673d5f2f8 100644 --- a/website/content/en/docs/golang/quickstart.md +++ b/website/content/en/docs/golang/legacy/quickstart.md @@ -1,9 +1,11 @@ --- -title: Golang Based Operator Quickstart +title: Golang Based Operator Quickstart (Legacy) linkTitle: Quickstart weight: 2 --- +**Note:** This guide is for the legacy CLI and project layout. See the [new docs][new_docs] for the [Kubebuilder aligned CLI][new_CLI] and project layout. + This guide walks through an example of building a simple memcached-operator using the operator-sdk CLI tool and controller-runtime library API. ## Create a new project @@ -829,11 +831,11 @@ When the operator is not running in a cluster, the Manager will return an error [enqueue_requests_from_map_func]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/handler#EnqueueRequestsFromMapFunc [event_handler_godocs]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/handler#hdr-EventHandlers -[event_filtering]:/docs/golang/references/event-filtering/ +[event_filtering]:/docs/golang/legacy/references/event-filtering/ [controller_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#Options [controller_godocs]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller [controller-runtime-reconcile-godoc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler -[operator_scope]:/docs/operator-scope/ +[operator_scope]:/docs/legacy-common/operator-scope/ [pod_eviction_timeout]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options [lease_split_brain]: https://github.com/kubernetes/client-go/blob/30b06a83d67458700a5378239df6b96948cb9160/tools/leaderelection/leaderelection.go#L21-L24 @@ -841,21 +843,23 @@ When the operator is not running in a cluster, the Manager will return an error [leader_with_lease]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/leaderelection [memcached_handler]: ../example/memcached-operator/handler.go.tmpl [memcached_controller]: https://github.com/operator-framework/operator-sdk/blob/master/example/memcached-operator/memcached_controller.go.tmpl -[layout_doc]:/docs/golang/references/project-layout/ +[layout_doc]:/docs/golang/legacy/references/project-layout/ [homebrew_tool]:https://brew.sh/ [go_mod_wiki]: https://github.com/golang/go/wiki/Modules [go_vendoring]: https://blog.gopheracademy.com/advent-2015/vendor-folder/ [scheme_package]:https://github.com/kubernetes/client-go/blob/master/kubernetes/scheme/register.go [deployments_register]: https://github.com/kubernetes/api/blob/master/apps/v1/register.go#L41 -[doc_client_api]:/docs/golang/references/client/ +[doc_client_api]:/docs/golang/legacy/references/client/ [runtime_package]: https://godoc.org/k8s.io/apimachinery/pkg/runtime [manager_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Manager [controller-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller [request-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request [result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result -[metrics_doc]: /docs/golang/monitoring/ +[metrics_doc]:/docs/golang/legacy/monitoring/ [multi-namespaced-cache-builder]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder [scheme_builder]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/scheme#Builder [typical-status-properties]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties [godoc-conditions]: https://godoc.org/github.com/operator-framework/operator-sdk/pkg/status#Conditions [olm-user-guide]: /docs/olm-integration/user-guide +[new_docs]:/docs/golang/new/quickstart +[new_CLI]:/docs/new-cli \ No newline at end of file diff --git a/website/content/en/docs/golang/references/_index.md b/website/content/en/docs/golang/legacy/references/_index.md similarity index 100% rename from website/content/en/docs/golang/references/_index.md rename to website/content/en/docs/golang/legacy/references/_index.md diff --git a/website/content/en/docs/golang/references/client.md b/website/content/en/docs/golang/legacy/references/client.md similarity index 100% rename from website/content/en/docs/golang/references/client.md rename to website/content/en/docs/golang/legacy/references/client.md diff --git a/website/content/en/docs/golang/references/event-filtering.md b/website/content/en/docs/golang/legacy/references/event-filtering.md similarity index 100% rename from website/content/en/docs/golang/references/event-filtering.md rename to website/content/en/docs/golang/legacy/references/event-filtering.md diff --git a/website/content/en/docs/golang/references/logging.md b/website/content/en/docs/golang/legacy/references/logging.md similarity index 100% rename from website/content/en/docs/golang/references/logging.md rename to website/content/en/docs/golang/legacy/references/logging.md diff --git a/website/content/en/docs/golang/references/markers.md b/website/content/en/docs/golang/legacy/references/markers.md similarity index 100% rename from website/content/en/docs/golang/references/markers.md rename to website/content/en/docs/golang/legacy/references/markers.md diff --git a/website/content/en/docs/golang/references/project-layout.md b/website/content/en/docs/golang/legacy/references/project-layout.md similarity index 100% rename from website/content/en/docs/golang/references/project-layout.md rename to website/content/en/docs/golang/legacy/references/project-layout.md diff --git a/website/content/en/docs/golang/unit-testing.md b/website/content/en/docs/golang/legacy/unit-testing.md similarity index 98% rename from website/content/en/docs/golang/unit-testing.md rename to website/content/en/docs/golang/legacy/unit-testing.md index 035fd68896..3b3db9d5a4 100644 --- a/website/content/en/docs/golang/unit-testing.md +++ b/website/content/en/docs/golang/legacy/unit-testing.md @@ -253,10 +253,10 @@ func TestMemcachedController(t *testing.T) { [doc-e2e-test]: ../e2e-tests -[doc-client]: /docs/golang/references/client/ +[doc-client]:/docs/golang/legacy/references/client/ [doc-cr-fake-client]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/client/fake [repo-memcached-reconcile]: https://github.com/operator-framework/operator-sdk-samples/blob/4c6934448684a6953ece4d3d9f3f77494b1c125e/memcached-operator/pkg/controller/memcached/memcached_controller.go#L82 [doc-reconcile]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/reconcile#Reconciler [code-test-example]: https://github.com/operator-framework/operator-sdk-samples/blob/master/go/memcached-operator/pkg/controller/memcached/memcached_controller_test.go#L25 -[user-guide]: /docs/golang/quickstart/#register-with-the-managers-scheme +[user-guide]:/docs/golang/legacy/quickstart/#register-with-the-managers-scheme [ocp-doc-v1-route]: https://docs.openshift.com/container-platform/3.11/rest_api/apis-route.openshift.io/v1.Route.html diff --git a/website/content/en/docs/golang/new/_index.md b/website/content/en/docs/golang/new/_index.md new file mode 100644 index 0000000000..eee29e9338 --- /dev/null +++ b/website/content/en/docs/golang/new/_index.md @@ -0,0 +1,4 @@ +--- +title: Golang Based Operators - New CLI +weight: 20 +--- diff --git a/website/content/en/docs/kubebuilder/advanced-topics.md b/website/content/en/docs/golang/new/advanced-topics.md similarity index 98% rename from website/content/en/docs/kubebuilder/advanced-topics.md rename to website/content/en/docs/golang/new/advanced-topics.md index 9ea5147932..b076687bf4 100644 --- a/website/content/en/docs/kubebuilder/advanced-topics.md +++ b/website/content/en/docs/golang/new/advanced-topics.md @@ -1,4 +1,8 @@ -# Advanced Topics +--- +title: Advanced Topics +linkTitle: Advanced Topics +weight: 50 +--- ### Manage CR status conditions @@ -118,7 +122,7 @@ To learn about how metrics work in the Operator SDK read the [metrics section][m To implement complex deletion logic, you can add a finalizer to your Custom Resource. This will prevent your Custom Resource from being deleted until you remove the finalizer (ie, after your cleanup logic has successfully run). For more information, see the -[official Kubernetes documentation on finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers). +[official Kubernetes documentation on finalizers](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers). **Example:** diff --git a/website/content/en/docs/kubebuilder/crds-scope.md b/website/content/en/docs/golang/new/crds-scope.md similarity index 96% rename from website/content/en/docs/kubebuilder/crds-scope.md rename to website/content/en/docs/golang/new/crds-scope.md index f8da5a365d..964918ce30 100644 --- a/website/content/en/docs/kubebuilder/crds-scope.md +++ b/website/content/en/docs/golang/new/crds-scope.md @@ -1,3 +1,9 @@ +--- +title: CRD Scope +linkTitle: CRD Scope +weight: 30 +--- + ## Overview The CustomResourceDefinition (CRD) scope can also be changed for cluster-scoped operators so that there is only a single @@ -91,5 +97,5 @@ spec: ``` [RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ -[manager_user_guide]: /docs/golang/quickstart/#manager +[manager_user_guide]:/docs/golang/new/quickstart/#manager [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options diff --git a/website/content/en/docs/golang/installation.md b/website/content/en/docs/golang/new/installation.md similarity index 100% rename from website/content/en/docs/golang/installation.md rename to website/content/en/docs/golang/new/installation.md diff --git a/website/content/en/docs/kubebuilder/operator-scope.md b/website/content/en/docs/golang/new/operator-scope.md similarity index 98% rename from website/content/en/docs/kubebuilder/operator-scope.md rename to website/content/en/docs/golang/new/operator-scope.md index c1bcacd06c..d2d090e001 100644 --- a/website/content/en/docs/kubebuilder/operator-scope.md +++ b/website/content/en/docs/golang/new/operator-scope.md @@ -1,4 +1,8 @@ -# Operator Scope +--- +title: Operators Scope +linkTitle: Operator Scope +weight: 20 +--- ## Overview @@ -265,5 +269,5 @@ if strings.Contains(namespace, ",") { [k8s-rbac]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ [kube-rbac-proxy]: https://github.com/brancz/kube-rbac-proxy [rbac-clusterrole]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole -[crd-scope-doc]: crds-scope +[crd-scope-doc]: /docs/golang/new/crds-scope/ [rbac-markers]: https://book.kubebuilder.io/reference/markers/rbac.html \ No newline at end of file diff --git a/website/content/en/docs/kubebuilder/migration/project_migration_guide.md b/website/content/en/docs/golang/new/project_migration_guide.md similarity index 96% rename from website/content/en/docs/kubebuilder/migration/project_migration_guide.md rename to website/content/en/docs/golang/new/project_migration_guide.md index 478f40af60..cde1c93a32 100644 --- a/website/content/en/docs/kubebuilder/migration/project_migration_guide.md +++ b/website/content/en/docs/golang/new/project_migration_guide.md @@ -1,6 +1,12 @@ +--- +title: Migrating Legacy Projects +linkTitle: Migrating Legacy Projects +weight: 300 +--- + # Overview -This guide walks through the steps required to migrate an operator from an Operator SDK project layout to a Kubebuilder project layout. +This guide walks through the steps required to migrate an operator from a legacy Operator SDK project layout to a Kubebuilder aligned project layout. The document considers [memcached operator][memcached-operator] as an example to describe the process of migrating an operator built using Operator SDK to a runnable Kubebuilder project. @@ -149,7 +155,7 @@ To update `config/rbac/role.yaml` after changing the markers, run `make manifest The project can now be built and the operator can be deployed on cluster. For further steps regarding the deployment of operator, creation of custom resource and cleaning up of resources, refer to [quickstart guide][kb_quickstart]. -[memcached-operator]: /docs/golang/quickstart.md +[memcached-operator]:/docs/golang/new/quickstart/ [git_tool]: https://git-scm.com/downloads [go_tool]: https://golang.org/dl/ [kubectl_tool]: https://github.com/kubernetes/minikube#installation @@ -163,5 +169,5 @@ The project can now be built and the operator can be deployed on cluster. For fu [memcached_cr]: https://github.com/operator-framework/operator-sdk-samples/blob/master/go/memcached-operator/deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml [memcached_types]: https://github.com/operator-framework/operator-sdk-samples/blob/master/go/memcached-operator/pkg/apis/cache/v1alpha1/memcached_types.go [kb_memcached_controller]: https://github.com/operator-framework/operator-sdk/blob/master/example/kb-memcached-operator/memcached_controller.go.tmpl -[kb_quickstart]: /docs/kubebuilder/quickstart.md -[install_guide]: /docs/install-operator-sdk.md +[kb_quickstart]: /docs/golang/new/quickstart/ +[install_guide]: /docs/install-operator-sdk/ diff --git a/website/content/en/docs/kubebuilder/quickstart.md b/website/content/en/docs/golang/new/quickstart.md similarity index 94% rename from website/content/en/docs/kubebuilder/quickstart.md rename to website/content/en/docs/golang/new/quickstart.md index 54adcc6133..0f0ea10926 100644 --- a/website/content/en/docs/kubebuilder/quickstart.md +++ b/website/content/en/docs/golang/new/quickstart.md @@ -1,6 +1,10 @@ +--- +title: Golang Based Operator Quickstart +linkTitle: Quickstart +weight: 10 +--- -**NOTE:** This is a WIP doc for the Kubebuilder integration effort. This new CLI and workflow is currently alpha and there may be breaking changes. -Please refer to the [quickstart guide][legacy_quickstart_doc] for the default CLI and workflow. +**NOTE:** For the SDK versions prior to `v0.19.0` please consult the [legacy docs][legacy_quickstart_doc] for the [legacy CLI][legacy_CLI] and project. This guide walks through an example of building a simple memcached-operator using the operator-sdk CLI tool and controller-runtime library API. @@ -56,8 +60,6 @@ mgr, err := manager.New(cfg, manager.Options{ #### Operator scope -> **// TODO:** Update [operator scope doc][operator_scope] and update commands that rely on WATCH_NAMESPACE being defined and sourced from `deploy/operator.yaml`. - Read the [operator scope][operator_scope] documentation on how to run your operator as namespace-scoped vs cluster-scoped. By default the main program will set the manager's namespace using the value of `WATCH_NAMESPACE` env defined in `deploy/operator.yaml`. @@ -254,8 +256,6 @@ return ctrl.Result{RequeueAfter: time.Second*5}, nil For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api]. -> **// TODO:** Should we point to the client API doc after the integration? - ### Specify permissions and generate RBAC manifests The controller needs certain RBAC permissions to interact with the resources it manages. These are specified via [RBAC markers][rbac_markers] like the following: @@ -323,8 +323,6 @@ Push the image to a repository: $ make docker-push IMG=quay.io/$USERNAME/memcached-operator:v0.0.1 ``` -> **// TODO:** Mention how to use `buildah build` by just updating the Makefile? - **Note**: The name and tag of the image (`IMG=/:tag`) in both the commands can also be set in the Makefile. Modify the line which has `IMG ?= controller:latest` to set your desired default image name. @@ -459,16 +457,16 @@ Also see the [advanced topics][advanced_topics] doc for more use cases and under [enqueue_requests_from_map_func]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/handler#EnqueueRequestsFromMapFunc [event_handler_godocs]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/handler#hdr-EventHandlers -[event_filtering]:/docs/golang/references/event-filtering/ +[event_filtering]:/docs/golang/new/references/event-filtering/ [controller_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#Options [controller_godocs]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller -[operator_scope]:/docs/operator-scope/ +[operator_scope]:/docs/golang/new/operator-scope/ [memcached_handler]: ../example/memcached-operator/handler.go.tmpl [kubebuilder_layout_doc]:https://book.kubebuilder.io/cronjob-tutorial/basic-project.html [homebrew_tool]:https://brew.sh/ [go_mod_wiki]: https://github.com/golang/go/wiki/Modules [go_vendoring]: https://blog.gopheracademy.com/advent-2015/vendor-folder/ -[doc_client_api]:/docs/golang/references/client/ +[doc_client_api]:/docs/golang/new/references/client/ [manager_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Manager [controller-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller [request-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request @@ -481,17 +479,18 @@ Also see the [advanced topics][advanced_topics] doc for more use cases and under [kb_controller_doc]: https://book.kubebuilder.io/cronjob-tutorial/controller-overview.html [kb_api_doc]: https://book.kubebuilder.io/cronjob-tutorial/new-api.html [controller_tools]: https://sigs.k8s.io/controller-tools -[doc-validation-schema]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#specifying-a-structural-schema +[doc-validation-schema]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema [generating-crd]: https://book.kubebuilder.io/reference/generating-crd.html [markers]: https://book.kubebuilder.io/reference/markers.html [crd-markers]: https://book.kubebuilder.io/reference/markers/crd-validation.html [rbac-markers]: https://book.kubebuilder.io/reference/markers/rbac.html [memcached_controller]: https://github.com/operator-framework/operator-sdk/blob/master/example/kb-memcached-operator/memcached_controller.go.tmpl [builder_godocs]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/builder#example-Builder -[legacy_quickstart_doc]: /docs/golang/quickstart/ +[legacy_quickstart_doc]:/docs/golang/legacy/quickstart/ [activate_modules]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support -[advanced_topics]: /docs/kubebuilder/advanced-topics/ -[create_a_webhook]: /docs/kubebuilder/webhooks.md +[advanced_topics]: /docs/golang/new/advanced-topics/ +[create_a_webhook]: /docs/golang/new/webhooks/ [status_marker]: https://book.kubebuilder.io/reference/generating-crd.html#status -[status_subresource]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#status-subresource +[status_subresource]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource [API-groups]:https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups +[legacy_CLI]:/docs/cli diff --git a/website/content/en/docs/golang/new/references/_index.md b/website/content/en/docs/golang/new/references/_index.md new file mode 100644 index 0000000000..73d8d747d0 --- /dev/null +++ b/website/content/en/docs/golang/new/references/_index.md @@ -0,0 +1,5 @@ +--- +title: Golang Based Operator Reference +linkTitle: Reference +weight: 100 +--- \ No newline at end of file diff --git a/website/content/en/docs/kubebuilder/references/client.md b/website/content/en/docs/golang/new/references/client.md similarity index 98% rename from website/content/en/docs/kubebuilder/references/client.md rename to website/content/en/docs/golang/new/references/client.md index 0d10da30bc..cd447a30c6 100644 --- a/website/content/en/docs/kubebuilder/references/client.md +++ b/website/content/en/docs/golang/new/references/client.md @@ -1,3 +1,9 @@ +--- +title: Controller Runtime Client API +linkTitle: Controller Runtime Client API +weight: 10 +--- + ## Overview The [`controller-runtime`][repo-controller-runtime] library provides various abstractions to watch and reconcile resources in a Kubernetes cluster via CRUD (Create, Update, Delete, as well as Get and List in this case) operations. Operators use at least one controller to perform a coherent set of tasks within a cluster, usually through a combination of CRUD operations. The Operator SDK uses controller-runtime's [Client][doc-client-client] interface, which provides the interface for these operations. @@ -568,4 +574,4 @@ func labelsForApp(name string) map[string]string { [doc-reconcile-reconciler]:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler [doc-osdk-handle]:https://github.com/operator-framework/operator-sdk/blob/master/design/milestone-0.0.2/action-api.md#handler [doc-types-nsname]:https://godoc.org/k8s.io/apimachinery/pkg/types#NamespacedName -[cr-status-subresource]:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#status-subresource +[cr-status-subresource]:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource diff --git a/website/content/en/docs/kubebuilder/references/event-filtering.md b/website/content/en/docs/golang/new/references/event-filtering.md similarity index 99% rename from website/content/en/docs/kubebuilder/references/event-filtering.md rename to website/content/en/docs/golang/new/references/event-filtering.md index 95ef675aa3..ea193ad2b9 100644 --- a/website/content/en/docs/kubebuilder/references/event-filtering.md +++ b/website/content/en/docs/golang/new/references/event-filtering.md @@ -1,8 +1,8 @@ - +weight: 30 +--- [Events][doc_event] are produced by [Sources][doc_source] assigned to resources a controller is watching. These events are transformed into Requests by [EventHandlers][doc_eventhandler] and passed to `Reconcile()`. [Predicates][doc_predicate] allow controllers to filter events before they are provided to EventHandlers. Filtering is useful because your controller may only want to handle specific types of events. Filtering also helps reduce chattiness with the API server, as `Reconcile()` is only called for events transformed by EventHandlers. diff --git a/website/content/en/docs/kubebuilder/references/logging.md b/website/content/en/docs/golang/new/references/logging.md similarity index 99% rename from website/content/en/docs/kubebuilder/references/logging.md rename to website/content/en/docs/golang/new/references/logging.md index fa2123eb87..893881cc4c 100644 --- a/website/content/en/docs/kubebuilder/references/logging.md +++ b/website/content/en/docs/golang/new/references/logging.md @@ -1,4 +1,10 @@ +--- +title: Logging +linkTitle: Logging +weight: 20 +--- +# Overview Operator SDK-generated operators use the [`logr`][godoc_logr] interface to log. This log interface has several backends such as [`zap`][repo_zapr], which the SDK uses in generated code by default. [`logr.Logger`][godoc_logr_logger] exposes [structured logging][site_struct_logging] methods that help create machine-readable logs and adding a wealth of information to log records. diff --git a/website/content/en/docs/kubebuilder/references/markers.md b/website/content/en/docs/golang/new/references/markers.md similarity index 99% rename from website/content/en/docs/kubebuilder/references/markers.md rename to website/content/en/docs/golang/new/references/markers.md index 7131c70a0e..985a742575 100644 --- a/website/content/en/docs/kubebuilder/references/markers.md +++ b/website/content/en/docs/golang/new/references/markers.md @@ -1,8 +1,8 @@ - +weight: 40 +--- This document describes [code markers][markers] supported by the SDK. diff --git a/website/content/en/docs/kubebuilder/webhooks.md b/website/content/en/docs/golang/new/webhooks.md similarity index 96% rename from website/content/en/docs/kubebuilder/webhooks.md rename to website/content/en/docs/golang/new/webhooks.md index d8ed274ea6..8e14c17299 100644 --- a/website/content/en/docs/kubebuilder/webhooks.md +++ b/website/content/en/docs/golang/new/webhooks.md @@ -1,5 +1,8 @@ - -**NOTE:** This is a WIP doc for the Kubebuilder integration effort. This new CLI and workflow is currently alpha and there may be breaking changes. +--- +title: Admission Webhooks +linkTitle: Admission Webhooks +weight: 40 +--- ## Create a validating or mutating Admission Webhook @@ -198,8 +201,8 @@ memcached-operator-controller-manager 1/1 1 1 10m memcached-sample 5/5 5 5 3m ``` -[quickstart_run_as_deployment]: /docs/kubebuilder/quickstart/#2-run-as-a-deployment-inside-the-cluster -[quickstart_create_a_cr]: /docs/kubebuilder/quickstart/#create-a-memcached-cr +[quickstart_run_as_deployment]: /docs/golang/new/quickstart/#2-run-as-a-deployment-inside-the-cluster +[quickstart_create_a_cr]: /docs/golang/new/quickstart/#create-a-memcached-cr [kubebuilder_admission_controllers]: https://book.kubebuilder.io/reference/admission-webhook.html [kubebuilder_cronjob_webhook]: https://book.kubebuilder.io/cronjob-tutorial/webhook-implementation.html diff --git a/website/content/en/docs/helm/quickstart.md b/website/content/en/docs/helm/quickstart.md index eaea6b0b06..610d4c7440 100644 --- a/website/content/en/docs/helm/quickstart.md +++ b/website/content/en/docs/helm/quickstart.md @@ -307,7 +307,7 @@ kubectl delete -f deploy/crds/example.com_nginxes_crd.yaml **NOTE** Additional CR/CRD's can be added to the project by running, for example, the command :`operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=AppService` For more information, refer [cli][addcli] doc. -[operator-scope]: /docs/operator-scope +[operator-scope]: /docs/legacy-common/operator-scope [layout-doc]: /docs/helm/reference/scaffolding [helm-charts]:https://helm.sh/docs/topics/charts/ [helm-values]:https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing diff --git a/website/content/en/docs/crds-scope.md b/website/content/en/docs/legacy-common/crds-scope.md similarity index 98% rename from website/content/en/docs/crds-scope.md rename to website/content/en/docs/legacy-common/crds-scope.md index 08cb349961..b7affbbbf4 100644 --- a/website/content/en/docs/crds-scope.md +++ b/website/content/en/docs/legacy-common/crds-scope.md @@ -88,5 +88,5 @@ marker `// +kubebuilder:resource:path=,scope=Cluster` ``` [RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ -[manager_user_guide]: /docs/golang/quickstart/#manager +[manager_user_guide]:/docs/golang/legacy/quickstart/#manager [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options diff --git a/website/content/en/docs/operator-scope.md b/website/content/en/docs/legacy-common/operator-scope.md similarity index 97% rename from website/content/en/docs/operator-scope.md rename to website/content/en/docs/legacy-common/operator-scope.md index af5caac64f..6b75fd9940 100644 --- a/website/content/en/docs/operator-scope.md +++ b/website/content/en/docs/legacy-common/operator-scope.md @@ -97,6 +97,6 @@ With the above changes the specified manifests should look as follows: ``` [RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ -[manager_user_guide]: /docs/golang/quickstart/#manager +[manager_user_guide]:/docs/golang/legacy/quickstart/#manager [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options -[crd-scope-doc]: /docs/crds-scope \ No newline at end of file +[crd-scope-doc]: /docs/legacy-common/crds-scope \ No newline at end of file diff --git a/website/content/en/docs/migration/v0.1.0-migration-guide.md b/website/content/en/docs/migration/v0.1.0-migration-guide.md index b235b7b1cb..2f9948d137 100644 --- a/website/content/en/docs/migration/v0.1.0-migration-guide.md +++ b/website/content/en/docs/migration/v0.1.0-migration-guide.md @@ -309,7 +309,7 @@ At this point you should be able to build and run your operator to verify that i [controller-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller [request-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request [result-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result -[client-api-doc]: ../../golang/references/client +[client-api-doc]: ../../golang/legacy/references/client [manager-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager -[register-3rd-party-resources]: ../../golang/quickstart#adding-3rd-party-resources-to-your-operator -[user-guide-build-run]: ../../golang/quickstart#build-and-run-the-operator +[register-3rd-party-resources]: ../../golang/legacy/quickstart#adding-3rd-party-resources-to-your-operator +[user-guide-build-run]: ../../golang/legacy/quickstart#build-and-run-the-operator diff --git a/website/content/en/docs/migration/version-upgrade-guide.md b/website/content/en/docs/migration/version-upgrade-guide.md index abfbca94e1..d78ffdc36b 100644 --- a/website/content/en/docs/migration/version-upgrade-guide.md +++ b/website/content/en/docs/migration/version-upgrade-guide.md @@ -1197,12 +1197,12 @@ first `COPY` from `COPY /*.yaml manifests/` to `COPY deploy/olm-catalog/ --version --kind + +Create resource will prompt the user for if it should scaffold the Resource and / or Controller. To only +scaffold a Controller for an existing Resource, select "n" for Resource. To only define +the schema for a Resource without writing a Controller, select "n" for Controller. + +After the scaffold is written, api will run make on the project. + + +``` +operator-sdk [flags] +``` + +### Examples + +``` + + # Initialize your project + operator-sdk init --domain example.com --license apache2 --owner "The Kubernetes authors" + + # Create a frigates API with Group: ship, Version: v1beta1 and Kind: Frigate + operator-sdk create api --group ship --version v1beta1 --kind Frigate + + # Edit the API Scheme + nano api/v1beta1/frigate_types.go + + # Edit the Controller + nano controllers/frigate_controller.go + + # Install CRDs into the Kubernetes cluster using kubectl apply + make install + + # Regenerate code and run against the Kubernetes cluster configured by ~/.kube/config + make run + +``` + +### Options + +``` + -h, --help help for operator-sdk + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk alpha](../operator-sdk_alpha) - Run an alpha subcommand +* [operator-sdk build](../operator-sdk_build) - Compiles code and builds artifacts +* [operator-sdk bundle](../operator-sdk_bundle) - Manage operator bundle metadata +* [operator-sdk completion](../operator-sdk_completion) - Generators for shell completions +* [operator-sdk create](../operator-sdk_create) - Scaffold a Kubernetes API or webhook +* [operator-sdk generate](../operator-sdk_generate) - Invokes a specific generator +* [operator-sdk init](../operator-sdk_init) - Initialize a new project +* [operator-sdk new](../operator-sdk_new) - Creates a new operator application +* [operator-sdk olm](../operator-sdk_olm) - Manage the Operator Lifecycle Manager installation in your cluster +* [operator-sdk version](../operator-sdk_version) - Prints the version of operator-sdk + diff --git a/website/content/en/docs/new-cli/operator-sdk_alpha.md b/website/content/en/docs/new-cli/operator-sdk_alpha.md new file mode 100644 index 0000000000..5ea6b57a3d --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_alpha.md @@ -0,0 +1,28 @@ +--- +title: "operator-sdk alpha" +--- +## operator-sdk alpha + +Run an alpha subcommand + +### Synopsis + +Run an alpha subcommand + +### Options + +``` + -h, --help help for alpha +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk alpha scorecard](../operator-sdk_alpha_scorecard) - Runs scorecard + diff --git a/website/content/en/docs/new-cli/operator-sdk_alpha_scorecard.md b/website/content/en/docs/new-cli/operator-sdk_alpha_scorecard.md new file mode 100644 index 0000000000..d6e097cd11 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_alpha_scorecard.md @@ -0,0 +1,42 @@ +--- +title: "operator-sdk alpha scorecard" +--- +## operator-sdk alpha scorecard + +Runs scorecard + +### Synopsis + +Has flags to configure dsl, bundle, and selector. This command takes +one argument, either a bundle image or directory containing manifests and metadata. +If the argument holds an image tag, it must be present remotely. + +``` +operator-sdk alpha scorecard [flags] +``` + +### Options + +``` + -c, --config string path to scorecard config file + -h, --help help for scorecard + --kubeconfig string kubeconfig path + -L, --list Option to enable listing which tests are run + -n, --namespace string namespace to run the test images in (default "default") + -o, --output string Output format for results. Valid values: text, json (default "text") + -l, --selector string label selector to determine which tests are run + -s, --service-account string Service account to use for tests (default "default") + -x, --skip-cleanup Disable resource cleanup after tests are run + -w, --wait-time duration seconds to wait for tests to complete. Example: 35s (default 30s) +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk alpha](../operator-sdk_alpha) - Run an alpha subcommand + diff --git a/website/content/en/docs/new-cli/operator-sdk_build.md b/website/content/en/docs/new-cli/operator-sdk_build.md new file mode 100644 index 0000000000..8c7100ec8c --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_build.md @@ -0,0 +1,46 @@ +--- +title: "operator-sdk build" +--- +## operator-sdk build + +Compiles code and builds artifacts + +### Synopsis + +The operator-sdk build command compiles the Operator code into an executable binary +and generates the Dockerfile manifest. + +'< image >' is the container image to be built, e.g. "quay.io/example/operator:v0.0.1". +This image will be automatically set in the deployment manifests. + +After build completes, the image would be built locally in docker. Then it needs to +be pushed to remote registry. +For example: + + $ operator-sdk build quay.io/example/operator:v0.0.1 + $ docker push quay.io/example/operator:v0.0.1 + + +``` +operator-sdk build [flags] +``` + +### Options + +``` + --go-build-args string Extra Go build arguments as one string such as "-ldflags -X=main.xyz=abc" + -h, --help help for build + --image-build-args string Extra image build arguments as one string such as "--build-arg https_proxy=$https_proxy" + --image-builder string Tool to build OCI images. One of: [docker, podman, buildah] (default "docker") +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. + diff --git a/website/content/en/docs/new-cli/operator-sdk_bundle.md b/website/content/en/docs/new-cli/operator-sdk_bundle.md new file mode 100644 index 0000000000..3bd31cb42f --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_bundle.md @@ -0,0 +1,37 @@ +--- +title: "operator-sdk bundle" +--- +## operator-sdk bundle + +Manage operator bundle metadata + +### Synopsis + +Manage bundle builds, bundle metadata generation, and bundle validation. +An operator bundle is a portable operator packaging format understood by Kubernetes +native software, like the Operator Lifecycle Manager. + +More information about operator bundles and metadata: +https://github.com/operator-framework/operator-registry#manifest-format. + +More information about the integration with OLM via SDK: +https://sdk.operatorframework.io/docs/olm-integration/ + + +### Options + +``` + -h, --help help for bundle +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk bundle validate](../operator-sdk_bundle_validate) - Validate an operator bundle image + diff --git a/website/content/en/docs/new-cli/operator-sdk_bundle_validate.md b/website/content/en/docs/new-cli/operator-sdk_bundle_validate.md new file mode 100644 index 0000000000..27e4aafb0c --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_bundle_validate.md @@ -0,0 +1,71 @@ +--- +title: "operator-sdk bundle validate" +--- +## operator-sdk bundle validate + +Validate an operator bundle image + +### Synopsis + +The 'operator-sdk bundle validate' command can validate both content and +format of an operator bundle image or an operator bundles directory on-disk +containing operator metadata and manifests. This command will exit with an +exit code of 1 if any validation errors arise, and 0 if only warnings arise or +all validators pass. + +More information about operator bundles and metadata: +https://github.com/operator-framework/operator-registry#manifest-format. + +NOTE: if validating an image, the image must exist in a remote registry, not +just locally. + + +``` +operator-sdk bundle validate [flags] +``` + +### Examples + +``` +The following command flow will generate test-operator bundle image manifests +and validate them, assuming a bundle for 'test-operator' version v0.1.0 exists at +/deploy/olm-catalog/test-operator/manifests: + + # Generate manifests locally. + $ operator-sdk bundle create --generate-only + + # Validate the directory containing manifests and metadata. + $ operator-sdk bundle validate ./deploy/olm-catalog/test-operator + +To build and validate an image: + + # Create a registry namespace or use an existing one. + $ export NAMESPACE= + + # Build and push the image using the docker CLI. + $ operator-sdk bundle create quay.io/$NAMESPACE/test-operator:v0.1.0 + $ docker push quay.io/$NAMESPACE/test-operator:v0.1.0 + + # Ensure the image with modified metadata and Dockerfile is valid. + $ operator-sdk bundle validate quay.io/$NAMESPACE/test-operator:v0.1.0 + + +``` + +### Options + +``` + -h, --help help for validate + -b, --image-builder string Tool to extract bundle image data. Only used when validating a bundle image. One of: [docker, podman] (default "docker") +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk bundle](../operator-sdk_bundle) - Manage operator bundle metadata + diff --git a/website/content/en/docs/new-cli/operator-sdk_completion.md b/website/content/en/docs/new-cli/operator-sdk_completion.md new file mode 100644 index 0000000000..a1a5d31e08 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_completion.md @@ -0,0 +1,29 @@ +--- +title: "operator-sdk completion" +--- +## operator-sdk completion + +Generators for shell completions + +### Synopsis + +Generators for shell completions + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk completion bash](../operator-sdk_completion_bash) - Generate bash completions +* [operator-sdk completion zsh](../operator-sdk_completion_zsh) - Generate zsh completions + diff --git a/website/content/en/docs/new-cli/operator-sdk_completion_bash.md b/website/content/en/docs/new-cli/operator-sdk_completion_bash.md new file mode 100644 index 0000000000..fc4e7aedb8 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_completion_bash.md @@ -0,0 +1,31 @@ +--- +title: "operator-sdk completion bash" +--- +## operator-sdk completion bash + +Generate bash completions + +### Synopsis + +Generate bash completions + +``` +operator-sdk completion bash [flags] +``` + +### Options + +``` + -h, --help help for bash +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk completion](../operator-sdk_completion) - Generators for shell completions + diff --git a/website/content/en/docs/new-cli/operator-sdk_completion_zsh.md b/website/content/en/docs/new-cli/operator-sdk_completion_zsh.md new file mode 100644 index 0000000000..ffc73a02e7 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_completion_zsh.md @@ -0,0 +1,31 @@ +--- +title: "operator-sdk completion zsh" +--- +## operator-sdk completion zsh + +Generate zsh completions + +### Synopsis + +Generate zsh completions + +``` +operator-sdk completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk completion](../operator-sdk_completion) - Generators for shell completions + diff --git a/website/content/en/docs/new-cli/operator-sdk_create.md b/website/content/en/docs/new-cli/operator-sdk_create.md new file mode 100644 index 0000000000..432a789956 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_create.md @@ -0,0 +1,29 @@ +--- +title: "operator-sdk create" +--- +## operator-sdk create + +Scaffold a Kubernetes API or webhook + +### Synopsis + +Scaffold a Kubernetes API or webhook. + +### Options + +``` + -h, --help help for create +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk create api](../operator-sdk_create_api) - Scaffold a Kubernetes API +* [operator-sdk create webhook](../operator-sdk_create_webhook) - Scaffold a webhook for an API resource + diff --git a/website/content/en/docs/new-cli/operator-sdk_create_api.md b/website/content/en/docs/new-cli/operator-sdk_create_api.md new file mode 100644 index 0000000000..d88451973a --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_create_api.md @@ -0,0 +1,36 @@ +--- +title: "operator-sdk create api" +--- +## operator-sdk create api + +Scaffold a Kubernetes API + +### Synopsis + +Scaffold a Kubernetes API. + +For project-specific information, run this command in the root directory of a +project. + +Note: unable to find configuration file, project must be initialized + +``` +operator-sdk create api [flags] +``` + +### Options + +``` + -h, --help help for api +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk create](../operator-sdk_create) - Scaffold a Kubernetes API or webhook + diff --git a/website/content/en/docs/new-cli/operator-sdk_create_webhook.md b/website/content/en/docs/new-cli/operator-sdk_create_webhook.md new file mode 100644 index 0000000000..7eebb95023 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_create_webhook.md @@ -0,0 +1,36 @@ +--- +title: "operator-sdk create webhook" +--- +## operator-sdk create webhook + +Scaffold a webhook for an API resource + +### Synopsis + +Scaffold a webhook for an API resource. + +For project-specific information, run this command in the root directory of a +project. + +Note: unable to find configuration file, project must be initialized + +``` +operator-sdk create webhook [flags] +``` + +### Options + +``` + -h, --help help for webhook +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk create](../operator-sdk_create) - Scaffold a Kubernetes API or webhook + diff --git a/website/content/en/docs/new-cli/operator-sdk_generate.md b/website/content/en/docs/new-cli/operator-sdk_generate.md new file mode 100644 index 0000000000..c16e6ac258 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_generate.md @@ -0,0 +1,29 @@ +--- +title: "operator-sdk generate" +--- +## operator-sdk generate + +Invokes a specific generator + +### Synopsis + +The 'operator-sdk generate' command invokes a specific generator to generate +code or manifests. + +### Options + +``` + -h, --help help for generate +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk generate bundle](../operator-sdk_generate_bundle) - Generates bundle data for the operator + diff --git a/website/content/en/docs/new-cli/operator-sdk_generate_bundle.md b/website/content/en/docs/new-cli/operator-sdk_generate_bundle.md new file mode 100644 index 0000000000..c53376dc14 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_generate_bundle.md @@ -0,0 +1,135 @@ +--- +title: "operator-sdk generate bundle" +--- +## operator-sdk generate bundle + +Generates bundle data for the operator + +### Synopsis + + + Running 'generate bundle' is the first step to publishing your operator to a catalog + and/or deploying it with OLM. This command generates a set of bundle manifests, + metadata, and a bundle.Dockerfile for your operator, and will interactively ask + for UI metadata, an important component of publishing your operator, by default unless + a bundle for your operator exists or you set '--interactive=false'. + + Set '--version' to supply a semantic version for your bundle if you are creating one + for the first time or upgrading an existing one. + + If '--output-dir' is set and you wish to build bundle images from that directory, + either manually update your bundle.Dockerfile or set '--overwrite'. + + More information on bundles: + https://github.com/operator-framework/operator-registry/#manifest-format + + +``` +operator-sdk generate bundle [flags] +``` + +### Examples + +``` + + # Using the example 'memcached-operator' and assuming a directory structure + # similar to the following exists: + $ tree api/ config/ + api/ + └── v1alpha1 + ├── groupversion_info.go + ├── memcached_types.go + └── zz_generated.deepcopy.go + config/ + ├── bundle + │   └── kustomization.yaml + ├── crd + │   ├── bases + │   │   └── cache.my.domain_memcacheds.yaml + │   ├── kustomization.yaml + │   ├── kustomizeconfig.yaml + │   ... + ├── default + │   ├── kustomization.yaml + │   ... + ├── manager + │   ├── kustomization.yaml + │   └── manager.yaml + ... + + # Generate bundle files and build your bundle image with these 'make' recipes: + $ make bundle + $ export USERNAME= + $ export BUNDLE_IMG=quay.io/$USERNAME/memcached-operator-bundle:v0.0.1 + $ make bundle-build BUNDLE_IMG=$BUNDLE_IMG + + # The above recipe runs the following commands manually. First it creates bundle + # manifests, metadata, and a bundle.Dockerfile: + $ make manifests + /home/user/go/bin/controller-gen "crd:trivialVersions=true" rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases + $ operator-sdk generate bundle -q --kustomize + + Display name for the operator (required): + > memcached-operator + ... + + $ kustomize build config/bundle | operator-sdk generate bundle --manifests --metadata --overwrite --version 0.0.1 + Generating bundle manifest version 0.0.1 + ... + + # After running the above commands, you should see: + $ tree config/bundle + config/bundle + ├── bases + │   └── memcached-operator.clusterserviceversion.yaml + ├── kustomization.yaml + ├── manifests + │   ├── cache.my.domain_memcacheds.yaml + │   └── memcached-operator.clusterserviceversion.yaml + └── metadata + └── annotations.yaml + + # Then it validates your bundle files and builds your bundle image: + $ operator-sdk bundle validate config/bundle + $ docker build -f bundle.Dockerfile -t $BUNDLE_IMG . + Sending build context to Docker daemon 42.33MB + Step 1/9 : FROM scratch + ... + + # You can then push your bundle image: + $ make docker-push IMG=$BUNDLE_IMG + +``` + +### Options + +``` + --apis-dir string Root directory for API type defintions + --channels string A comma-separated list of channels the bundle belongs to (default "alpha") + --crds-dir string Root directory for CustomResoureDefinition manifests + --default-channel string The default channel for the bundle + --deploy-dir string Root directory for operator manifests such as Deployments and RBAC, ex. 'deploy'. This directory is different from that passed to --input-dir + -h, --help help for bundle + --input-dir string Directory to read an existing bundle from. This directory is the parent of your bundle 'manifests' directory, and different from --deploy-dir + --interactive When set or no bundle base exists, an interactive command prompt will be presented to accept bundle ClusterServiceVersion metadata + --kustomize Generate kustomize bases + --manifests Generate bundle manifests + --metadata Generate bundle metadata and Dockerfile + --operator-name string Name of the bundle's operator + --output-dir string Directory to write the bundle to + --overwrite Overwrite the bundle's metadata and Dockerfile if they exist + -q, --quiet Run in quiet mode + --stdout Write bundle manifest to stdout + -v, --version string Semantic version of the operator in the generated bundle. Only set if creating a new bundle or upgrading your operator +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk generate](../operator-sdk_generate) - Invokes a specific generator + diff --git a/website/content/en/docs/new-cli/operator-sdk_init.md b/website/content/en/docs/new-cli/operator-sdk_init.md new file mode 100644 index 0000000000..aa850bcb82 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_init.md @@ -0,0 +1,60 @@ +--- +title: "operator-sdk init" +--- +## operator-sdk init + +Initialize a new project + +### Synopsis + +Initialize a new project including vendor/ directory and Go package directories. + +Writes the following files: +- a boilerplate license file +- a PROJECT file with the domain and repo +- a Makefile to build the project +- a go.mod with project dependencies +- a Kustomization.yaml for customizating manifests +- a Patch file for customizing image for manager manifests +- a Patch file for enabling prometheus metrics +- a cmd/manager/main.go to run + +project will prompt the user to run 'dep ensure' after writing the project files. + + +``` +operator-sdk init [flags] +``` + +### Examples + +``` + # Scaffold a project using the apache2 license with "The Kubernetes authors" as owners + operator-sdk init --project-version=2 --domain example.org --license apache2 --owner "The Kubernetes authors" + +``` + +### Options + +``` + --domain string domain for groups (default "my.domain") + --fetch-deps ensure dependencies are downloaded (default true) + -h, --help help for init + --license string license to use to boilerplate, may be one of 'apache2', 'none' (default "apache2") + --owner string owner to add to the copyright + --plugins strings Name and optionally version of the plugin to initialize the project with. Available plugins: ("go.kubebuilder.io/v2", "go.kubebuilder.io/v2") + --project-version string project version, possible values: ("2", "3-alpha") (default "3-alpha") + --repo string name to use for go module (e.g., github.com/user/repo), defaults to the go package of the current working directory. + --skip-go-version-check if specified, skip checking the Go version +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. + diff --git a/website/content/en/docs/new-cli/operator-sdk_new.md b/website/content/en/docs/new-cli/operator-sdk_new.md new file mode 100644 index 0000000000..2dbd49b6f7 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_new.md @@ -0,0 +1,91 @@ +--- +title: "operator-sdk new" +--- +## operator-sdk new + +Creates a new operator application + +### Synopsis + +The operator-sdk new command creates a new operator application and +generates a default directory layout based on the input . + + is the project name of the new operator. (e.g app-operator) + + +``` +operator-sdk new [flags] +``` + +### Examples + +``` + # Create a new project directory + $ mkdir $HOME/projects/example.com/ + $ cd $HOME/projects/example.com/ + + # Ansible project + $ operator-sdk new app-operator --type=ansible \ + --api-version=app.example.com/v1alpha1 \ + --kind=AppService + + # Helm project + $ operator-sdk new app-operator --type=helm \ + --api-version=app.example.com/v1alpha1 \ + --kind=AppService + + $ operator-sdk new app-operator --type=helm \ + --api-version=app.example.com/v1alpha1 \ + --kind=AppService \ + --helm-chart=myrepo/app + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=myrepo/app + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=myrepo/app \ + --helm-chart-version=1.2.3 + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=app \ + --helm-chart-repo=https://charts.mycompany.com/ + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=app \ + --helm-chart-repo=https://charts.mycompany.com/ \ + --helm-chart-version=1.2.3 + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=/path/to/local/chart-directories/app/ + + $ operator-sdk new app-operator --type=helm \ + --helm-chart=/path/to/local/chart-archives/app-1.2.3.tgz + +``` + +### Options + +``` + --api-version string Kubernetes apiVersion and has a format of $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1) + --crd-version string CRD version to generate (default "v1") + --generate-playbook Generate a playbook skeleton. (Only used for --type ansible) + --git-init Initialize the project directory as a git repository (default false) + --helm-chart string Initialize helm operator with existing helm chart (, /, or local path). Valid only for --type helm + --helm-chart-repo string Chart repository URL for the requested helm chart, Valid only for --type helm + --helm-chart-version string Specific version of the helm chart (default is latest version). Valid only for --type helm + -h, --help help for new + --kind string Kubernetes resource Kind name. (e.g AppService) + --skip-generation Skip generation of deepcopy and OpenAPI code and OpenAPI CRD specs + --type string Type of operator to initialize (choices: "ansible" or "helm") +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. + diff --git a/website/content/en/docs/new-cli/operator-sdk_olm.md b/website/content/en/docs/new-cli/operator-sdk_olm.md new file mode 100644 index 0000000000..b49bb71a51 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_olm.md @@ -0,0 +1,30 @@ +--- +title: "operator-sdk olm" +--- +## operator-sdk olm + +Manage the Operator Lifecycle Manager installation in your cluster + +### Synopsis + +Manage the Operator Lifecycle Manager installation in your cluster + +### Options + +``` + -h, --help help for olm +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. +* [operator-sdk olm install](../operator-sdk_olm_install) - Install Operator Lifecycle Manager in your cluster +* [operator-sdk olm status](../operator-sdk_olm_status) - Get the status of the Operator Lifecycle Manager installation in your cluster +* [operator-sdk olm uninstall](../operator-sdk_olm_uninstall) - Uninstall Operator Lifecycle Manager from your cluster + diff --git a/website/content/en/docs/new-cli/operator-sdk_olm_install.md b/website/content/en/docs/new-cli/operator-sdk_olm_install.md new file mode 100644 index 0000000000..3c62a05715 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_olm_install.md @@ -0,0 +1,33 @@ +--- +title: "operator-sdk olm install" +--- +## operator-sdk olm install + +Install Operator Lifecycle Manager in your cluster + +### Synopsis + +Install Operator Lifecycle Manager in your cluster + +``` +operator-sdk olm install [flags] +``` + +### Options + +``` + -h, --help help for install + --timeout duration time to wait for the command to complete before failing (default 2m0s) + --version string version of OLM resources to install (default "latest") +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk olm](../operator-sdk_olm) - Manage the Operator Lifecycle Manager installation in your cluster + diff --git a/website/content/en/docs/new-cli/operator-sdk_olm_status.md b/website/content/en/docs/new-cli/operator-sdk_olm_status.md new file mode 100644 index 0000000000..ee841af122 --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_olm_status.md @@ -0,0 +1,33 @@ +--- +title: "operator-sdk olm status" +--- +## operator-sdk olm status + +Get the status of the Operator Lifecycle Manager installation in your cluster + +### Synopsis + +Get the status of the Operator Lifecycle Manager installation in your cluster + +``` +operator-sdk olm status [flags] +``` + +### Options + +``` + -h, --help help for status + --olm-namespace string namespace where OLM is installed (default "olm") + --timeout duration time to wait for the command to complete before failing (default 2m0s) +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk olm](../operator-sdk_olm) - Manage the Operator Lifecycle Manager installation in your cluster + diff --git a/website/content/en/docs/new-cli/operator-sdk_olm_uninstall.md b/website/content/en/docs/new-cli/operator-sdk_olm_uninstall.md new file mode 100644 index 0000000000..935ac066ff --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_olm_uninstall.md @@ -0,0 +1,32 @@ +--- +title: "operator-sdk olm uninstall" +--- +## operator-sdk olm uninstall + +Uninstall Operator Lifecycle Manager from your cluster + +### Synopsis + +Uninstall Operator Lifecycle Manager from your cluster + +``` +operator-sdk olm uninstall [flags] +``` + +### Options + +``` + -h, --help help for uninstall + --timeout duration time to wait for the command to complete before failing (default 2m0s) +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk olm](../operator-sdk_olm) - Manage the Operator Lifecycle Manager installation in your cluster + diff --git a/website/content/en/docs/new-cli/operator-sdk_version.md b/website/content/en/docs/new-cli/operator-sdk_version.md new file mode 100644 index 0000000000..027a3a998f --- /dev/null +++ b/website/content/en/docs/new-cli/operator-sdk_version.md @@ -0,0 +1,31 @@ +--- +title: "operator-sdk version" +--- +## operator-sdk version + +Prints the version of operator-sdk + +### Synopsis + +Prints the version of operator-sdk + +``` +operator-sdk version [flags] +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + --verbose Enable verbose logging +``` + +### SEE ALSO + +* [operator-sdk](../operator-sdk) - Development kit for building Kubernetes extensions and tools. + diff --git a/website/content/en/docs/olm-integration/generating-a-csv.md b/website/content/en/docs/olm-integration/generating-a-csv.md index fc036ba7ff..408a98fbe0 100644 --- a/website/content/en/docs/olm-integration/generating-a-csv.md +++ b/website/content/en/docs/olm-integration/generating-a-csv.md @@ -205,4 +205,4 @@ Optional: [doc-bundle]:https://github.com/operator-framework/operator-registry/blob/6893d19/README.md#manifest-format [install-modes]:https://github.com/operator-framework/operator-lifecycle-manager/blob/4197455/Documentation/design/building-your-csv.md#operator-metadata [olm-capabilities]:/docs/operator-capabilities/ -[csv-markers]:/docs/golang/references/markers +[csv-markers]:/docs/golang/legacy/references/markers diff --git a/website/content/en/docs/olm-integration/user-guide.md b/website/content/en/docs/olm-integration/user-guide.md index ff38f04045..04b2f7cce2 100644 --- a/website/content/en/docs/olm-integration/user-guide.md +++ b/website/content/en/docs/olm-integration/user-guide.md @@ -265,7 +265,7 @@ manager tool [`opm`][opm] to manage index images. Once one has been built, follo the OLM [docs][doc-olm-index] on adding an index to a cluster registry. -[sdk-user-guide-go]:/docs/golang/quickstart +[sdk-user-guide-go]:/docs/golang/legacy/quickstart [sdk-user-guide-ansible]:/docs/ansible/quickstart [sdk-user-guide-helm]:/docs/helm/quickstart [olm]:https://github.com/operator-framework/operator-lifecycle-manager/ @@ -286,7 +286,7 @@ the OLM [docs][doc-olm-index] on adding an index to a cluster registry. [cli-bundle-validate]:/docs/cli/operator-sdk_bundle_validate [doc-bundle-cli]:/docs/olm-integration/cli-overview [cli-generate-csv]:/docs/cli/operator-sdk_generate_csv -[csv-markers]:/docs/golang/references/markers +[csv-markers]:/docs/golang/legacy/references/markers [doc-run-olm]:/docs/olm-integration/olm-deployment/#operator-sdk-run-packagemanifests-command-overview [doc-olm-index]:https://github.com/operator-framework/operator-registry#using-the-index-with-operator-lifecycle-manager [index-image]:https://github.com/operator-framework/operator-registry#building-an-index-of-operators-using-opm diff --git a/website/content/en/docs/scorecard/scorecard-alpha.md b/website/content/en/docs/scorecard/scorecard-alpha.md index ef4f1231f9..83e7e4f956 100644 --- a/website/content/en/docs/scorecard/scorecard-alpha.md +++ b/website/content/en/docs/scorecard/scorecard-alpha.md @@ -211,7 +211,7 @@ Writing custom tests in other programming languages is possible if the test image follows the above guidelines. -[cli-scorecard]: ../../cli/operator-sdk_alpha_scorecard/ +[cli-scorecard]: /docs/cli/operator-sdk_alpha_scorecard/ [sample-config]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/alpha/testdata/bundle/tests/scorecard/config.yaml [scorecard-struct]: https://github.com/operator-framework/operator-sdk/blob/master/pkg/apis/scorecard/v1alpha2/types.go [olm-bundle]:https://github.com/operator-framework/operator-registry#manifest-format diff --git a/website/content/en/docs/scorecard/scorecard.md b/website/content/en/docs/scorecard/scorecard.md index 2ed4cc85ea..52ec98bc97 100644 --- a/website/content/en/docs/scorecard/scorecard.md +++ b/website/content/en/docs/scorecard/scorecard.md @@ -662,8 +662,8 @@ Once done, follow the steps in this [document][olm-deploy-operator] to bundle yo - As of now, using the scorecard with a CSV does not permit multiple CR manifests to be set through the CLI/config/CSV annotations. You will have to tear down your operator in the cluster, re-deploy, and re-run the scorecard for each CR being tested. In the future the scorecard will fully support testing multiple CR's without requiring users to teardown/standup each time. - You can either set `cr-manifest` or your CSV's [`metadata.annotations['alm-examples']`][olm-csv-alm-examples] to provide CR's to the scorecard, but not both. -[cli-scorecard]: ../../cli/operator-sdk_scorecard -[writing-tests]: ../../golang/e2e-tests +[cli-scorecard]: /docs/cli/operator-sdk_scorecard +[writing-tests]: ../../golang/legacy/e2e-tests [owned-crds]: https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md#owned-crds [alm-examples]: https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md#crd-templates [viper]: https://github.com/spf13/viper/blob/master/README.md diff --git a/website/layouts/index.html b/website/layouts/index.html index 64b0e7a7d7..0a2387ae3c 100644 --- a/website/layouts/index.html +++ b/website/layouts/index.html @@ -58,7 +58,7 @@

    Go

  • Use the SDK CLI to build and generate the operator deployment manifests
    • - + Develop with Go