|
| 1 | +# User Experience CLI Improvements | Phase 1 |
| 2 | + |
| 3 | +Implementation Owner: @joelanford |
| 4 | + |
| 5 | +Status: Draft |
| 6 | + |
| 7 | +[Background](#Background) |
| 8 | + |
| 9 | +[Goal](#Goal) |
| 10 | + |
| 11 | +[Use cases](#Use_cases) |
| 12 | + |
| 13 | +[Proposed CLI commands](#Proposed_CLI_commands) |
| 14 | + |
| 15 | +[References](#References) |
| 16 | + |
| 17 | +## Background |
| 18 | + |
| 19 | +The SDK CLI is one of the primary tools in the Operator Framework for operator developers and |
| 20 | +deployers. However, the current user experience (UX) leaves a lot to be desired. Currently, the |
| 21 | +tools and documentation that help a user create, develop, test, package, run, and publish an |
| 22 | +operator are spread among many different repositories, making for a steep learning curve for |
| 23 | +newcomers. |
| 24 | + |
| 25 | +## Goal |
| 26 | + |
| 27 | +Implement a proof-of-concept with an initial set of CLI additions to support a simplified workflow for an Operator SDK user to run an Operator SDK-developed project in a cluster using the Operator Lifecyle Manager (OLM). |
| 28 | + |
| 29 | +## Use cases |
| 30 | + |
| 31 | +1. As an operator developer, I want to deploy OLM to a development cluster. |
| 32 | +2. As an operator developer, I want to create the resources necessary for running my operator via OLM. |
| 33 | +3. As an operator developer, I want to run my operator via OLM. |
| 34 | + |
| 35 | +## Proposed CLI commands |
| 36 | + |
| 37 | +### `operator-sdk alpha` |
| 38 | + |
| 39 | +Many other Kubernetes CLI projects (e.g. `kubebuilder`, `kubectl`, and `kubeadm`) have an `alpha` subcommand tree that is used to introduce new functionality to the CLI while giving users a cue that the functionality is subject to change. This gives maintainers flexibility while iterating on new CLI features. |
| 40 | + |
| 41 | +The general idea is that new subcommand features should be introduced under the `alpha` subcommand (e.g. `operator-sdk alpha my-command`) and then moved to their own top-level commands once the implementation has matured (e.g. `operator-sdk my-command`). |
| 42 | + |
| 43 | +### `operator-sdk alpha olm init` |
| 44 | + |
| 45 | +Checks cluster facts based on the current kubeconfig context (e.g. cluster type, version, OLM status), and ensures OLM is running. Using this command with unsupported clusters results in a failure. |
| 46 | + |
| 47 | +#### OCP/OKD |
| 48 | + |
| 49 | +For clusters where OLM is expected to be installed by default, this command will print OLM's current status and exit. |
| 50 | + |
| 51 | +#### Upstream Kubernetes |
| 52 | + |
| 53 | +For other clusters that meet OLM's prerequisites, the command will check to see if OLM is already deployed. If so, it will print OLM's current status and exit. If not, it will deploy OLM using the `upstream` manifests from OLM's repository at the version specified by the `--olm-version` flag, based on the following URL pattern: |
| 54 | + |
| 55 | +`https://raw.githubusercontent.com/operator-framework/operator-lifecycle-manager/master/deploy/upstream/manifests/<olm-version>/` |
| 56 | + |
| 57 | +Each resource that is applied will be logged so that users can manually backout the OLM deployment if desired. Once the manifests have been applied, the command will wait until OLM is running (or until a specified timeout) and then print its status. |
| 58 | + |
| 59 | +#### Flags for `olm init` |
| 60 | + |
| 61 | +| Flag | Type | Description | |
| 62 | +|------------------|--------|-------------------------------------------------------------------------------------------------| |
| 63 | +| `--olm-version` | string | The version of OLM to deploy (default `latest`) | |
| 64 | +| `--timeout` | string | Timeout duration to wait for OLM to become ready before outputting status (default 60s) | |
| 65 | +| `--kubeconfig` | string | Path for custom Kubernetes client config file (overrides the default locations) | |
| 66 | + |
| 67 | +### `operator-sdk alpha olm up` |
| 68 | + |
| 69 | +Creates all necessary resources in the cluster to run the operator via OLM, waits for the operator to be deployed by OLM, and tails the operator log, similar to `operator-sdk up local`. When the user terminates the process or if a timeout or error occurs, all of the created resources will be cleaned up. |
| 70 | + |
| 71 | +Different clusters install OLM in different namespaces. Since `olm up` may need to create resources in these namespaces, the cluster fact collection used in `operator-sdk alpha olm init` should be used here as well to determine which OLM namespaces are in use. This cluster fact collection package should be maintained in a separate shared package within the SDK repo, such that it is decoupled and could be extracted into a separate `operator-framework-tools` (or similar) repo in the future. |
| 72 | + |
| 73 | +#### Prerequisites |
| 74 | + |
| 75 | +1. The operator container image referenced by the CSV is available to the cluster. |
| 76 | +2. An operator bundle on disk (created by `operator-sdk olm-catalog gen-csv`). |
| 77 | + |
| 78 | +#### Flags for `olm up` |
| 79 | + |
| 80 | +| Flag | Type | Description | |
| 81 | +|------------------|--------|-------------------------------------------------------------------------------------------------| |
| 82 | +| `--bundle-dir` | string | The directory containing the operator bundle (default `./deploy/olm-catalog/<operator-name>`) | |
| 83 | +| `--install-mode` | string | The [`InstallMode`][olm_install_modes] to use when running the operator, one of `OwnNamespace`, `SingleNamespace`, `MultiNamespace`, or `AllNamespaces` (default `OwnNamespace`). If using `MultiNamespace`, users can define the `OperatorGroup` target namespaces with `--install-mode=MultiNamespace=ns1,ns2,nsN` | |
| 84 | +| `--kubeconfig` | string | Path for custom Kubernetes client config file (overrides the default locations) | |
| 85 | +| `--namespace` | string | Namespace in which to deploy operator and RBAC rules (overrides namespace from current context). We'll verify this is compatible with the defined install mode. | |
| 86 | + |
| 87 | +#### Resources |
| 88 | + |
| 89 | +OLM uses Kubernetes APIs to learn about the set of operators that are available to be installed and to manage operator lifecycles (i.e. install, upgrade, uninstall). The following resources will be created in the cluster. |
| 90 | + |
| 91 | +| API Kind | Description | |
| 92 | +|-----------------|--------------| |
| 93 | +| `ConfigMap` | Contains catalog data created from the on-disk operator bundle. | |
| 94 | +| `CatalogSource` | Tells OLM where to find operator catalog data. This will refer to the catalog `ConfigMap`. | |
| 95 | +| `OperatorGroup` | Tells OLM which namespaces the operator will have RBAC permissions for. We'll configure it based on the `--install-mode` and `--namespace` flags. | |
| 96 | +| `Subscription` | Tells OLM to manage installation and upgrade of an operator in the namespace in which the `Subscription` is created. We'll create it based on the value of the `--namespace` flag. | |
| 97 | + |
| 98 | +**Open questions:** |
| 99 | +1. When the user aborts the process, should we handle cleanup for any of the InstallPlan, CSV, CRD, and CR resources? Which of these will be automatically garbage-collected? |
| 100 | + |
| 101 | +## References |
| 102 | + |
| 103 | +### Operator SDK |
| 104 | + |
| 105 | +* [GitHub][osdk_github] |
| 106 | +* [User Guide][osdk_user_guide] |
| 107 | +* [CLI Reference][osdk_cli] |
| 108 | + |
| 109 | +### Operator Registry |
| 110 | + |
| 111 | +* [GitHub][registry_github] |
| 112 | +* [Manifest format][registry_manifest_format] |
| 113 | + |
| 114 | +### Operator Lifecycle Manager |
| 115 | + |
| 116 | +* [GitHub][olm_github] |
| 117 | +* [Architecture][olm_arch] |
| 118 | + |
| 119 | +[osdk_github]: https://github.com/operator-framework/operator-sdk |
| 120 | +[osdk_user_guide]: https://github.com/operator-framework/operator-sdk/blob/master/doc/user-guide.md |
| 121 | +[osdk_cli]: https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md |
| 122 | + |
| 123 | + |
| 124 | +[registry_github]: https://github.com/operator-framework/operator-registry |
| 125 | +[registry_manifest_format]: https://github.com/operator-framework/operator-registry#manifest-format |
| 126 | + |
| 127 | +[olm_github]: https://github.com/operator-framework/operator-lifecycle-manager |
| 128 | +[olm_arch]: https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/architecture.md |
| 129 | +[olm_install_modes]: https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/operatorgroups.md#installmodes-and-supported-operatorgroups |
| 130 | + |
0 commit comments