github.com/operator-framework/operator-lifecycle-manager@v0.30.0/README.md (about)

     1  <img src="logo/logo.svg#gh-light-mode-only" height="125px" alt="Operator Lifecycle Manager"></img>
     2  <img src="logo/logo-dark-mode.svg#gh-dark-mode-only" height="125px" alt="Operator Lifecycle Manager"></img>
     3  
     4  [![Container Repository on Quay.io](https://quay.io/repository/operator-framework/olm/status "Container Repository on Quay.io")](https://quay.io/repository/operator-framework/olm)
     5  [![License](http://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
     6  [![Go Report Card](https://goreportcard.com/badge/github.com/operator-framework/operator-lifecycle-manager)](https://goreportcard.com/report/github.com/operator-framework/operator-lifecycle-manager)
     7  [![Slack Channel](https://img.shields.io/badge/chat-4A154B?logo=slack&logoColor=white "Slack Channel")](https://kubernetes.slack.com/archives/C0181L6JYQ2)
     8  
     9  ---
    10  > [!WARNING]  
    11  > This repository is associated with **Operator Lifecycle Manager** version 0 (v0) which is in maintenance mode. The community is excited to be working on a new design (v1) which intends to overcome a number of limitations of the v0 architecture, the primary repository for which is [operator controller](https://www.github.com/operator-framework/operator-controller).  
    12  
    13  In maintenance mode, we have the following changes to support expectations:
    14  1. We will accept no new features.
    15  2. We will accept no non-critical outage issues, defined here as a cluster-wide outage with no workaround.
    16  3. We will close backlog issues which do not meet the above criteria.
    17  4. We will continue to update the project to address emergent vulnerabilities on a best-effort basis.
    18  
    19  If you have any questions, please engage with us: [![Slack Channel](https://img.shields.io/badge/chat-4A154B?logo=slack&logoColor=white "Slack Channel")](https://kubernetes.slack.com/archives/C0181L6JYQ2)
    20  
    21  ---
    22  
    23  ## Documentation
    24  
    25  User documentation can be found on the [OLM website][olm-docs].
    26  
    27  ## Overview
    28  
    29  This project is a component of the [Operator Framework](https://github.com/operator-framework), an open source toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. Read more in the [introduction blog post](https://operatorhub.io/what-is-an-operator) and learn about practical use cases at the [OLM website][olm-docs].
    30  
    31  OLM extends Kubernetes to provide a declarative way to install, manage, and upgrade Operators and their dependencies in a cluster. It provides the following features:
    32  
    33  ### Over-the-Air Updates and Catalogs
    34  
    35  Kubernetes clusters are being kept up to date using elaborate update mechanisms today, more often automatically and in the background. Operators, being cluster extensions, should follow that. OLM has a concept of catalogs from which Operators are available to install and being kept up to date. In this model OLM allows maintainers granular authoring of the update path and gives commercial vendors a flexible publishing mechanism using channels.
    36  
    37  ### Dependency Model
    38  
    39  With OLMs packaging format Operators can express dependencies on the platform and on other Operators. They can rely on OLM to respect these requirements as long as the cluster is up. In this way, OLMs dependency model ensures Operators stay working during their long lifecycle across multiple updates of the platform or other Operators.
    40  
    41  ### Discoverability
    42  
    43  OLM advertises installed Operators and their services into the namespaces of tenants. They can discover which managed services are available and which Operator provides them. Administrators can rely on catalog content projected into a cluster, enabling discovery of Operators available to install.
    44  
    45  ### Cluster Stability
    46  
    47  Operators must claim ownership of their APIs. OLM will prevent conflicting Operators owning the same APIs being installed, ensuring cluster stability.
    48  
    49  ### Declarative UI controls
    50  
    51  Operators can behave like managed service providers. Their user interface on the command line are APIs. For graphical consoles OLM annotates those APIs with descriptors that drive the creation of rich interfaces and forms for users to interact with the Operator in a natural, cloud-like way.
    52  
    53  ## Prerequisites
    54  
    55  - [git][git_tool]
    56  - [go][go_tool] version v1.12+.
    57  - [docker][docker_tool] version 17.03+.
    58    - Alternatively [podman][podman_tool] `v1.2.0+` or [buildah][buildah_tool] `v1.7+`
    59  - [kubectl][kubectl_tool] version v1.11.3+.
    60  - Access to a Kubernetes v1.11.3+ cluster.
    61  
    62  ## Getting Started
    63  
    64  Check out the [Getting Started][olm-getting-started] section in the docs.
    65  
    66  ### Installation
    67  
    68  Install OLM on a Kubernetes cluster by following the [installation guide][installation-guide].
    69  
    70  For a complete end-to-end example of how OLM fits into the Operator Framework, see the [Operator Framework website](https://operatorframework.io/about/) and the [Getting Started guide on OperatorHub.io](https://operatorhub.io/getting-started).
    71  
    72  ## Contributing your Operator
    73  
    74  Have an awesome Operator you want to share? Checkout the [publishing docs](https://operatorhub.io/contribute) to learn about contributing to [OperatorHub.io](https://operatorhub.io/).
    75  
    76  ## Subscribe to a Package and Channel
    77  
    78  Cloud Services can be installed from the catalog by subscribing to a channel in the corresponding package.
    79  
    80  ## Kubernetes-native Applications
    81  
    82  An Operator is an application-specific controller that extends the Kubernetes API to create, configure, manage, and operate instances of complex applications on behalf of a user.
    83  
    84  OLM requires that applications be managed by an operator, but that doesn't mean that each application must write one from scratch. Depending on the level of control required you may:
    85  
    86  - Package up an existing set of resources for OLM with [helm-app-operator-kit](https://github.com/operator-framework/helm-app-operator-kit) without writing a single line of go.
    87  - Use the [operator-sdk](https://github.com/operator-framework/operator-sdk) to quickly build an operator from scratch.
    88  
    89  The primary vehicle for describing operator requirements with OLM is a [`ClusterServiceVersion`](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md). Once you have an application packaged for OLM, you can deploy it with OLM by creating its `ClusterServiceVersion` in a namespace with a supporting [`OperatorGroup`](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/operatorgroups.md).
    90  
    91  ClusterServiceVersions can be collected into `CatalogSource`s which will allow automated installation and dependency resolution via an `InstallPlan`, and can be kept up-to-date with a `Subscription`.
    92  
    93  Learn more about the components used by OLM by reading about the [architecture] and [philosophy].
    94  
    95  # Key Concepts
    96  
    97  ## CustomResourceDefinitions
    98  
    99  OLM standardizes interactions with operators by requiring that the interface to an operator be via the Kubernetes API. Because we expect users to define the interfaces to their applications, OLM currently uses CRDs to define the Kubernetes API interactions.
   100  
   101  Examples: [EtcdCluster CRD](https://github.com/redhat-openshift-ecosystem/community-operators-prod/blob/main/operators/etcd/0.9.4/manifests/etcdclusters.etcd.database.coreos.com.crd.yaml),
   102  [EtcdBackup CRD](https://github.com/redhat-openshift-ecosystem/community-operators-prod/blob/main/operators/etcd/0.9.4/manifests/etcdbackups.etcd.database.coreos.com.crd.yaml)
   103  
   104  ## Descriptors
   105  
   106  OLM introduces the notion of “descriptors” of both `spec` and `status` fields in kubernetes API responses. Descriptors are intended to indicate various properties of a field in order to make decisions about their content. For example, this can drive connecting two operators together (e.g. connecting the connection string from a mysql instance to a consuming application) and be used to drive rich interactions in a UI.
   107  
   108  [See an example of a ClusterServiceVersion with descriptors](https://github.com/redhat-openshift-ecosystem/community-operators-prod/blob/main/operators/etcd/0.9.2/etcdoperator.v0.9.2.clusterserviceversion.yaml)
   109  
   110  ## Dependency Resolution
   111  
   112  To minimize the effort required to run an application on kubernetes, OLM handles dependency discovery and resolution of applications running on OLM.
   113  
   114  This is achieved through additional metadata on the application definition. Each operator must define:
   115  
   116  - The CRDs that it is responsible for managing.
   117    - e.g., the etcd operator manages `EtcdCluster`.
   118  - The CRDs that it depends on.
   119    - e.g., the vault operator depends on `EtcdCluster`, because Vault is backed by etcd.
   120  
   121  Basic dependency resolution is then possible by finding, for each “required” CRD, the corresponding operator that manages it and installing it as well. Dependency resolution can be further constrained by the way a user interacts with catalogs.
   122  
   123  ### Granularity
   124  
   125  Dependency resolution is driven through the `(Group, Version, Kind)` of CRDs. This means that no updates can occur to a given CRD (of a particular Group, Version, Kind) unless they are completely backward compatible.
   126  
   127  There is no way to express a dependency on a particular version of an operator (e.g. `etcd-operator v0.9.0`) or application instance (e.g. `etcd v3.2.1`). This encourages application authors to depend on the interface and not the implementation.
   128  
   129  ## Discovery, Catalogs, and Automated Upgrades
   130  
   131  OLM has the concept of catalogs, which are repositories of application definitions and CRDs.
   132  
   133  Catalogs contain a set of Packages, which map “channels” to a particular application definition. Channels allow package authors to write different upgrade paths for different users (e.g. alpha vs. stable).
   134  
   135  Example: [etcd package](https://github.com/redhat-openshift-ecosystem/community-operators-prod/blob/main/operators/etcd/etcd.package.yaml)
   136  
   137  Users can subscribe to channels and have their operators automatically updated when new versions are released.
   138  
   139  Here's an example of a subscription:
   140  
   141  ```yaml
   142  apiVersion: operators.coreos.com/v1alpha1
   143  kind: Subscription
   144  metadata:
   145    name: etcd
   146    namespace: olm
   147  spec:
   148    channel: singlenamespace-alpha
   149    name: etcd
   150    source: operatorhubio-catalog
   151    sourceNamespace: olm
   152  ```
   153  
   154  This will keep the etcd `ClusterServiceVersion` up to date as new versions become available in the catalog.
   155  
   156  Catalogs are served internally over a grpc interface to OLM from [operator-registry](https://github.com/operator-framework/operator-registry) pods.  Catalog data such as `bundles` are documented [there](https://github.com/operator-framework/operator-registry#manifest-format) as well.
   157  
   158  ## Samples
   159  
   160  To explore any operator samples using the OLM, see the [https://operatorhub.io/](https://operatorhub.io/) and its resources in [Community Operators](https://github.com/k8s-operatorhub/community-operators/tree/main/operators).
   161  
   162  ## Community and how to get involved
   163  
   164  - [Operator framework community][operator-framework-community]
   165  - [Communication channels][operator-framework-communication]
   166  - [Project meetings][operator-framework-meetings]
   167  
   168  ## Contributing
   169  
   170  Check out the [contributor documentation][contributor-documentation]. Also, see the [proposal docs][proposals_docs] and issues for ongoing or planned work.
   171  
   172  ## Reporting bugs
   173  
   174  See [reporting bugs][bug_guide] for details about reporting any issues.
   175  
   176  ## Reporting flaky tests
   177  
   178  See [reporting flaky tests][flaky_test_guide] for details about reporting flaky tests.
   179  
   180  ## License
   181  
   182  Operator Lifecycle Manager is under Apache 2.0 license. See the [LICENSE][license_file] file for details.
   183  
   184  [architecture]: /doc/design/architecture.md
   185  [philosophy]: /doc/design/philosophy.md
   186  [proposals_docs]: ./doc/contributors/design-proposals
   187  [license_file]:./LICENSE
   188  [bug_guide]:./doc/dev/reporting_bugs.md
   189  [flaky_test_guide]:./doc/dev/reporting_flakes.md
   190  [git_tool]:https://git-scm.com/downloads
   191  [go_tool]:https://golang.org/dl/
   192  [docker_tool]:https://docs.docker.com/install/
   193  [podman_tool]:https://github.com/containers/libpod/blob/master/install.md
   194  [buildah_tool]:https://github.com/containers/buildah/blob/master/install.md
   195  [kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
   196  [olm-docs]: https://olm.operatorframework.io/
   197  [operator-framework-community]: https://github.com/operator-framework/community
   198  [operator-framework-communication]: https://github.com/operator-framework/community#get-involved
   199  [operator-framework-meetings]: https://github.com/operator-framework/community#meetings
   200  [contributor-documentation]: ./CONTRIBUTING.md
   201  [olm-getting-started]: https://olm.operatorframework.io/docs/getting-started/
   202  [installation-guide]: doc/install/install.md