github.com/operator-framework/operator-lifecycle-manager@v0.30.0/doc/design/architecture.md (about) 1 # Architecture 2 3 OLM is composed of two Operators: the OLM Operator and the Catalog Operator. 4 5 Each of these Operators is responsible for managing the CRDs that are the basis for the OLM framework: 6 7 | Resource | Short Name | Owner | Description | 8 |--------------------------|------------|---------|--------------------------------------------------------------------------------------------| 9 | ClusterServiceVersion | csv | OLM | application metadata: name, version, icon, required resources, installation, etc... | 10 | InstallPlan | ip | Catalog | calculated list of resources to be created in order to automatically install/upgrade a CSV | 11 | CatalogSource | catsrc | Catalog | a repository of CSVs, CRDs, and packages that define an application | 12 | Subscription | sub | Catalog | used to keep CSVs up to date by tracking a channel in a package | 13 | OperatorGroup | og | OLM | used to group multiple namespaces and prepare for use by an operator | 14 15 Each of these Operators are also responsible for creating resources: 16 17 | Operator | Creatable Resources | 18 |----------|----------------------------| 19 | OLM | Deployment | 20 | OLM | Service Account | 21 | OLM | (Cluster)Roles | 22 | OLM | (Cluster)RoleBindings | 23 | Catalog | Custom Resource Definition | 24 | Catalog | ClusterServiceVersion | 25 26 ## What is a ClusterServiceVersion 27 28 ClusterServiceVersion combines metadata and runtime information about a service that allows OLM to manage it. 29 30 ClusterServiceVersion: 31 32 - Metadata (name, description, version, links, labels, icon, etc) 33 - Install strategy 34 - Type: Deployment 35 - Set of service accounts / required permissions 36 - Set of deployments 37 38 - CRDs 39 - Type 40 - Owned - managed by this service 41 - Required - must exist in the cluster for this service to run 42 - Resources - a list of k8s resources that the Operator interacts with 43 - Descriptors - annotate CRD spec and status fields to provide semantic information 44 45 ## OLM Operator 46 47 The OLM Operator is responsible for installing applications defined by a `ClusterServiceVersion` resources once the required resources specified in the CSV are present in the cluster (the job of the Cluster Operator). This may be as simple as setting up a single `Deployment` resulting in an operator's pod becoming available. The OLM Operator is not concerned with the creation of the underlying resources. If this is not done manually, the Catalog Operator can help provide resolution of these needs. 48 49 This separation of concerns enables users incremental buy-in of the OLM framework components. Users can choose to manually create these resources, or define an InstallPlan for the Catalog Operator or allow the Catalog Operator to develop and implement the InstallPlan. An operator creator does not need to learn about the full operator package system before seeing a working operator. 50 51 While the OLM Operator is often configured to watch all namespaces, it can also be operated alongside other OLM Operators so long as they all manage separate namespaces defined by `OperatorGroups`. 52 53 ### ClusterServiceVersion Control Loop 54 55 ``` 56 +------------------------------------------------------+ 57 | | 58 | +--> Succeeded -+ 59 v | | 60 None --> Pending --> InstallReady --> Installing -| | 61 ^ +--> Failed <--+ 62 | | 63 +----------------------------------------------+ 64 \ / 65 +---------------------------------------------------------------+ 66 | 67 v 68 Replacing --> Deleting 69 ``` 70 *Note: The transition to replacing happens out-of-band when the controller detects a new CSV that replaces the current one.* 71 72 | Phase | Description | 73 |------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 74 | None | initial phase, once seen by the Operator, it is immediately transitioned to `Pending` | 75 | Pending | requirements in the CSV are not met, once they are this phase transitions to `InstallReady` | 76 | InstallReady | all requirements in the CSV are present, the Operator will begin executing the install strategy | 77 | Installing | the install strategy is being executed and resources are being created, but not all components are reporting as ready | 78 | Succeeded | the execution of the Install Strategy was successful; if requirements disappear, or an APIService cert needs to be rotated this may transition back to `Pending`; if an installed component disappears this may transition to `Failed`| 79 | Failed | upon failed execution of the Install Strategy, or an installed component disappears the CSV transitions to this phase; if the component can be recreated by OLM, this may transition to `Pending` | 80 | Replacing | a newer CSV that replaces this one has been discovered in the cluster. This status means the CSV is marked for GC | 81 | Deleting | the GC loop has determined this CSV is safe to delete from the cluster. It will disappear soon. | 82 > Note: In order to transition, a CSV must first be an active member of an OperatorGroup 83 84 ## Catalog Operator 85 86 The Catalog Operator is responsible for monitoring `Subscriptions`, `CatalogSources` and the catalogs themselves. When it finds a new or changed `Subscription`, it builds out the subscribed Operator. When it finds a new or changed CatalogSource it builds out the required catalog, if appropriate, and begins regular monitoring of the package in the catalog. The packages in the catalog will include various `ClusterServiceVersions`, `CustomResourceDefinitions` and a channel list for each package. A catalog has packages. A package has channels and CSVs. A Channels identifies a specific CSV. The CSVs identify specific CRDs. 87 88 A user wanting a specific operator creates a `Subscription` which identifies a catalog, operator and channel within that operator. The Catalog Operator then receives that information and queries the catalog for the latest version of the channel requested. Then it looks up the appropriate `ClusterServiceVersion` identified by the channel and turns that into an `InstallPlan`. When updates are found in the catalog for the channel, a similar process occurs resulting in a new `InstallPlan`. (Users can also create an InstallPlan resource directly, containing the names of the desired ClusterServiceVersions and an approval strategy.) 89 90 When the Catalog Operator find a new `InstallPlan`, even though it likely created it, it will create an "execution plan" and embed that into the `InstallPlan` to create all of the required resources. Once approved, whether manually or automatically, the Catalog Operator will implement its portion of the the execution plan, satisfying the underlying expectations of the OLM Operator. 91 92 The OLM Operator will then pickup the installation and carry it through to completion of everything required in the identified CSV. 93 94 ### InstallPlan Control Loop 95 96 ``` 97 None --> Planning +------>------->------> Installing +---> Complete 98 | ^ | 99 v | v 100 +--> RequiresApproval --+ Failed 101 ``` 102 103 | Phase | Description | 104 |------------------|------------------------------------------------------------------------------------------------| 105 | None | initial phase, once seen by the Operator, it is immediately transitioned to `Planning` | 106 | Planning | dependencies between resources are being resolved, to be stored in the InstallPlan `Status` | 107 | RequiresApproval | occurs when using manual approval, will not transition phase until `approved` field is true | 108 | Installing | waiting for reconciliation of required resource(OG/SA etc), or resolved resources in the 109 InstallPlan `Status` block are being created | 110 | Complete | all resolved resources in the `Status` block exist | 111 | Failed | occurs when resources fail to install or when bundle unpacking fails | 112 113 ### Subscription Control Loop 114 115 ``` 116 None --> UpgradeAvailable --> UpgradePending --> AtLatestKnown -+ 117 ^ | | 118 | v v 119 +----------<---------------<--------+---------<--------+ 120 ``` 121 122 | Phase | Description | 123 |------------------|---------------------------------------------------------------------------------------------------------------| 124 | None | initial phase, once seen by the Operator, it is immediately transitioned to `UpgradeAvailable` | 125 | UpgradeAvailable | catalog contains a CSV which replaces the `status.installedCSV`, but no `InstallPlan` has been created yet | 126 | UpgradePending | `InstallPlan` has been created (referenced in `status.installplan`) to install a new CSV | 127 | AtLatestKnown | `status.installedCSV` matches the latest available CSV in catalog | 128 129 ## Catalog (Registry) Design 130 131 The Catalog Registry stores CSVs and CRDs for creation in a cluster, and stores metadata about packages and channels. 132 133 A package manifest is an entry in the catalog registry that associates a package identity with sets of ClusterServiceVersions. Within a package, channels point to a particular CSV. Because CSVs explicitly reference the CSV that they replace, a package manifest provides the catalog Operator all of the information that is required to update a CSV to the latest version in a channel (stepping through each intermediate version). 134 135 ``` 136 Package {name} 137 | 138 +-- Channel {name} --> CSV {version} (--> CSV {version - 1} --> ...) 139 | 140 +-- Channel {name} --> CSV {version} 141 | 142 +-- Channel {name} --> CSV {version} 143 ```