metadata.name
A cluster service version (CSV), defined by a ClusterServiceVersion object, is a YAML manifest created from Operator metadata that assists Operator Lifecycle Manager (OLM) in running the Operator in a cluster. It is the metadata that accompanies an Operator container image, used to populate user interfaces with information such as its logo, description, and version. It is also a source of technical information that is required to run the Operator, like the RBAC rules it requires and which custom resources (CRs) it manages or depends on.
The Operator SDK includes the CSV generator to generate a CSV for the current Operator project, customized using information contained in YAML manifests and Operator source files.
A CSV-generating command removes the responsibility of Operator authors having in-depth OLM knowledge in order for their Operator to interact with OLM or publish metadata to the Catalog Registry. Further, because the CSV spec will likely change over time as new Kubernetes and OLM features are implemented, the Operator SDK is equipped to easily extend its update system to handle new CSV features going forward.
Operator bundle manifests, which include cluster service versions (CSVs), describe how to display, create, and manage an application with Operator Lifecycle Manager (OLM). The CSV generator in the Operator SDK, called by the generate bundle subcommand, is the first step towards publishing your Operator to a catalog and deploying it with OLM. The subcommand requires certain input manifests to construct a CSV manifest; all inputs are read when the command is invoked, along with a CSV base, to idempotently generate or regenerate a CSV.
Typically, the generate kustomize manifests subcommand would be run first to generate the input Kustomize bases that are consumed by the generate bundle subcommand. However, the Operator SDK provides the make bundle command, which automates several tasks, including running the following subcommands in order:
generate kustomize manifests
generate bundle
bundle validate
See Bundling an Operator for a full procedure that includes generating a bundle and CSV.
The make bundle command creates the following files and directories in your Operator project:
A bundle manifests directory named bundle/manifests that contains a ClusterServiceVersion (CSV) object
A bundle metadata directory named bundle/metadata
All custom resource definitions (CRDs) in a config/crd directory
A Dockerfile bundle.Dockerfile
The following resources are typically included in a CSV:
Defines Operator permissions within a namespace.
Defines cluster-wide Operator permissions.
Defines how an Operand of an Operator is run in pods.
Defines custom resources that your Operator reconciles.
Examples of resources adhering to the spec of a particular CRD.
The --version flag for the generate bundle subcommand supplies a semantic version for your bundle when creating one for the first time and when upgrading an existing one.
By setting the VERSION variable in your Makefile, the --version flag is automatically invoked using that value when the generate bundle subcommand is run by the make bundle command. The CSV version is the same as the Operator version, and a new CSV is generated when upgrading Operator versions.
Many CSV fields cannot be populated using generated, generic manifests that are not specific to Operator SDK. These fields are mostly human-written metadata about the Operator and various custom resource definitions (CRDs).
Operator authors must directly modify their cluster service version (CSV) YAML file, adding personalized data to the following required fields. The Operator SDK gives a warning during CSV generation when a lack of data in any of the required fields is detected.
The following tables detail which manually-defined CSV fields are required and which are optional.
| Field | Description |
|---|---|
|
A unique name for this CSV. Operator version should be included in the name to ensure uniqueness, for example |
|
The capability level according to the Operator maturity model. Options include |
|
A public name to identify the Operator. |
|
A short description of the functionality of the Operator. |
|
Keywords describing the Operator. |
|
Human or organizational entities maintaining the Operator, with a |
|
The provider of the Operator (usually an organization), with a |
|
Key-value pairs to be used by Operator internals. |
|
Semantic version of the Operator, for example |
|
Any CRDs the Operator uses. This field is populated automatically by the Operator SDK if any CRD YAML files are present in
|
| Field | Description |
|---|---|
|
The name of the CSV being replaced by this CSV. |
|
URLs (for example, websites and documentation) pertaining to the Operator or application being managed, each with a |
|
Selectors by which the Operator can pair resources in a cluster. |
|
A base64-encoded icon unique to the Operator, set in a |
|
The level of maturity the software has achieved at this version. Options include |
Further details on what data each field above should hold are found in the CSV spec.
|
Several YAML fields currently requiring user intervention can potentially be parsed from Operator code. |
Operator developers can manually define certain annotations in the metadata of a cluster service version (CSV) to enable features or highlight capabilities in user interfaces (UIs), such as OperatorHub.
The following table lists Operator metadata annotations that can be manually defined using metadata.annotations fields.
| Field | Description | ||
|---|---|---|---|
|
Provide custom resource definition (CRD) templates with a minimum set of configuration. Compatible UIs pre-fill this template for users to further customize. |
||
|
Specify a single required custom resource that must be created at the time that the Operator is installed. Must include a template that contains a complete YAML definition. |
||
|
Set a suggested namespace where the Operator should be deployed. |
||
|
Infrastructure features supported by the Operator. Users can view and filter by these features when discovering Operators through OperatorHub in the web console. Valid, case-sensitive values:
|
||
|
Free-form array for listing any specific subscriptions that are required to use the Operator. For example, |
||
|
Hides CRDs in the UI that are not meant for user manipulation. |
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'As an Operator author, your Operator must meet additional requirements to run properly in a restricted network, or disconnected, environment.
Replace hard-coded image references with environment variables.
In the cluster service version (CSV) of your Operator:
List any related images, or other container images that your Operator might require to perform their functions.
Reference all specified images by a digest (SHA) and not by a tag.
All dependencies of your Operator must also support running in a disconnected mode.
Your Operator must not require any off-cluster resources.
An Operator project with a CSV. The following procedure uses the Memcached Operator as an example for Go-, Ansible-, and Helm-based projects.
Set an environment variable for the additional image references used by the Operator in the config/manager/manager.yaml file:
config/manager/manager.yaml file...
spec:
...
spec:
...
containers:
- command:
- /manager
...
env:
- name: <related_image_environment_variable> (1)
value: "<related_image_reference_with_tag>" (2)| 1 | Define the environment variable, such as RELATED_IMAGE_MEMCACHED. |
| 2 | Set the related image reference and tag, such as docker.io/memcached:1.4.36-alpine. |
Replace hard-coded image references with environment variables in the relevant file for your Operator project type:
For Go-based Operator projects, add the environment variable to the controllers/memcached_controller.go file as shown in the following example:
controllers/memcached_controller.go file // deploymentForMemcached returns a memcached Deployment object
...
Spec: corev1.PodSpec{
Containers: []corev1.Container{{
- Image: "memcached:1.4.36-alpine", (1)
+ Image: os.Getenv("<related_image_environment_variable>"), (2)
Name: "memcached",
Command: []string{"memcached", "-m=64", "-o", "modern", "-v"},
Ports: []corev1.ContainerPort{{
...| 1 | Delete the image reference and tag. |
| 2 | Use the os.Getenv function to call the <related_image_environment_variable>. |
|
The |
For Ansible-based Operator projects, add the environment variable to the roles/memcached/tasks/main.yml file as shown in the following example:
roles/memcached/tasks/main.yml filespec:
containers:
- name: memcached
command:
- memcached
- -m=64
- -o
- modern
- -v
- image: "docker.io/memcached:1.4.36-alpine" (1)
+ image: "{{ lookup('env', '<related_image_environment_variable>') }}" (2)
ports:
- containerPort: 11211
...| 1 | Delete the image reference and tag. |
| 2 | Use the lookup function to call the <related_image_environment_variable>. |
For Helm-based Operator projects, add the overrideValues field to the watches.yaml file as shown in the following example:
watches.yaml file...
- group: demo.example.com
version: v1alpha1
kind: Memcached
chart: helm-charts/memcached
overrideValues: (1)
relatedImage: ${<related_image_environment_variable>} (2)| 1 | Add the overrideValues field. |
| 2 | Define the overrideValues field by using the <related_image_environment_variable>, such as RELATED_IMAGE_MEMCACHED. |
Add the value of the overrideValues field to the helm-charts/memchached/values.yaml file as shown in the following example:
helm-charts/memchached/values.yaml file...
relatedImage: ""Edit the chart template in the helm-charts/memcached/templates/deployment.yaml file as shown in the following example:
helm-charts/memcached/templates/deployment.yaml filecontainers:
- name: {{ .Chart.Name }}
securityContext:
- toYaml {{ .Values.securityContext | nindent 12 }}
image: "{{ .Values.image.pullPolicy }}
env: (1)
- name: related_image (2)
value: "{{ .Values.relatedImage }}" (3)| 1 | Add the env field. |
| 2 | Name the environment variable. |
| 3 | Define the value of the environment variable. |
Add the BUNDLE_GEN_FLAGS variable definition to your Makefile with the following changes:
Makefile BUNDLE_GEN_FLAGS ?= -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)
# USE_IMAGE_DIGESTS defines if images are resolved via tags or digests
# You can enable this value if you would like to use SHA Based Digests
# To enable set flag to true
USE_IMAGE_DIGESTS ?= false
ifeq ($(USE_IMAGE_DIGESTS), true)
BUNDLE_GEN_FLAGS += --use-image-digests
endif
...
- $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS) (1)
+ $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle $(BUNDLE_GEN_FLAGS) (2)
...| 1 | Delete this line in the Makefile. |
| 2 | Replace the line above with this line. |
To update your Operator image to use a digest (SHA) and not a tag, run the make bundle command and set USE_IMAGE_DIGESTS to true :
$ make bundle USE_IMAGE_DIGESTS=trueAdd the disconnected annotation, which indicates that the Operator works in a disconnected environment:
metadata:
annotations:
operators.openshift.io/infrastructure-features: '["disconnected"]'Operators can be filtered in OperatorHub by this infrastructure feature.
Operator Lifecycle Manager (OLM) assumes that all Operators run on Linux hosts. However, as an Operator author, you can specify whether your Operator supports managing workloads on other architectures, if worker nodes are available in the OpenShift Container Platform cluster.
If your Operator supports variants other than AMD64 and Linux, you can add labels to the cluster service version (CSV) that provides the Operator to list the supported variants. Labels indicating supported architectures and operating systems are defined by the following:
labels:
operatorframework.io/arch.<arch>: supported (1)
operatorframework.io/os.<os>: supported (2)| 1 | Set <arch> to a supported string. |
| 2 | Set <os> to a supported string. |
|
Only the labels on the channel head of the default channel are considered for filtering package manifests by label. This means, for example, that providing an additional architecture for an Operator in the non-default channel is possible, but that architecture is not available for filtering in the |
If a CSV does not include an os label, it is treated as if it has the following Linux support label by default:
labels:
operatorframework.io/os.linux: supportedIf a CSV does not include an arch label, it is treated as if it has the following AMD64 support label by default:
labels:
operatorframework.io/arch.amd64: supportedIf an Operator supports multiple node architectures or operating systems, you can add multiple labels, as well.
An Operator project with a CSV.
To support listing multiple architectures and operating systems, your Operator image referenced in the CSV must be a manifest list image.
For the Operator to work properly in restricted network, or disconnected, environments, the image referenced must also be specified using a digest (SHA) and not by a tag.
Add a label in the metadata.labels of your CSV for each supported architecture and operating system that your Operator supports:
labels:
operatorframework.io/arch.s390x: supported
operatorframework.io/os.zos: supported
operatorframework.io/os.linux: supported (1)
operatorframework.io/arch.amd64: supported (1)| 1 | After you add a new architecture or operating system, you must also now include the default os.linux and arch.amd64 variants explicitly. |
See the Image Manifest V 2, Schema 2 specification for more information on manifest lists.
The following strings are supported in Operator Lifecycle Manager (OLM) on OpenShift Container Platform when labeling or filtering Operators that support multiple architectures and operating systems:
| Architecture | String |
|---|---|
AMD64 |
|
64-bit PowerPC little-endian |
|
IBM Z |
|
| Operating system | String |
|---|---|
Linux |
|
z/OS |
|
|
Different versions of OpenShift Container Platform and other Kubernetes-based distributions might support a different set of architectures and operating systems. |
Some Operators must be deployed in a specific namespace, or with ancillary resources in specific namespaces, to work properly. If resolved from a subscription, Operator Lifecycle Manager (OLM) defaults the namespaced resources of an Operator to the namespace of its subscription.
As an Operator author, you can instead express a desired target namespace as part of your cluster service version (CSV) to maintain control over the final namespaces of the resources installed for their Operators. When adding the Operator to a cluster using OperatorHub, this enables the web console to autopopulate the suggested namespace for the cluster administrator during the installation process.
In your CSV, set the operatorframework.io/suggested-namespace annotation to your suggested namespace:
metadata:
annotations:
operatorframework.io/suggested-namespace: <namespace> (1)| 1 | Set your suggested namespace. |
Operator Lifecycle Manager (OLM) provides Operators with a channel to communicate complex states that influence OLM behavior while managing the Operator. By default, OLM creates an OperatorCondition custom resource definition (CRD) when it installs an Operator. Based on the conditions set in the OperatorCondition custom resource (CR), the behavior of OLM changes accordingly.
To support Operator conditions, an Operator must be able to read the OperatorCondition CR created by OLM and have the ability to:
Get the specific condition.
Set the status of a specific condition.
This can be accomplished by using the operator-lib library. An Operator author can provide a controller-runtime client in their Operator for the library to access the OperatorCondition CR owned by the Operator in the cluster.
The library provides a generic Conditions interface, which has the following methods to Get and Set a conditionType in the OperatorCondition CR:
GetTo get the specific condition, the library uses the client.Get function from controller-runtime, which requires an ObjectKey of type types.NamespacedName present in conditionAccessor.
SetTo update the status of the specific condition, the library uses the client.Update function from controller-runtime. An error occurs if the conditionType is not present in the CRD.
The Operator is allowed to modify only the status subresource of the CR. Operators can either delete or update the status.conditions array to include the condition. For more details on the format and description of the fields present in the conditions, see the upstream Condition GoDocs.
|
Operator SDK v1.10.1 supports |
An Operator project generated using the Operator SDK.
To enable Operator conditions in your Operator project:
In the go.mod file of your Operator project, add operator-framework/operator-lib as a required library:
module github.com/example-inc/memcached-operator
go 1.15
require (
k8s.io/apimachinery v0.19.2
k8s.io/client-go v0.19.2
sigs.k8s.io/controller-runtime v0.7.0
operator-framework/operator-lib v0.3.0
)Write your own constructor in your Operator logic that:
Accepts a controller-runtime client.
Accepts a conditionType.
Returns a Condition interface to update or add conditions.
Because OLM currently supports the Upgradeable condition, you can create an interface that has methods to access the Upgradeable condition. For example:
import (
...
apiv1 "github.com/operator-framework/api/pkg/operators/v1"
)
func NewUpgradeable(cl client.Client) (Condition, error) {
return NewCondition(cl, "apiv1.OperatorUpgradeable")
}
cond, err := NewUpgradeable(cl);In this example, the NewUpgradeable constructor is further used to create a variable cond of type Condition. The cond variable would in turn have Get and Set methods, which can be used for handling the OLM Upgradeable condition.
Webhooks allow Operator authors to intercept, modify, and accept or reject resources before they are saved to the object store and handled by the Operator controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these webhooks when they are shipped alongside your Operator.
The cluster service version (CSV) resource of an Operator can include a webhookdefinitions section to define the following types of webhooks:
Admission webhooks (validating and mutating)
Conversion webhooks
Add a webhookdefinitions section to the spec section of the CSV of your Operator and include any webhook definitions using a type of ValidatingAdmissionWebhook, MutatingAdmissionWebhook, or ConversionWebhook. The following example contains all three types of webhooks:
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
name: webhook-operator.v0.0.1
spec:
customresourcedefinitions:
owned:
- kind: WebhookTest
name: webhooktests.webhook.operators.coreos.io (1)
version: v1
install:
spec:
deployments:
- name: webhook-operator-webhook
...
...
...
strategy: deployment
installModes:
- supported: false
type: OwnNamespace
- supported: false
type: SingleNamespace
- supported: false
type: MultiNamespace
- supported: true
type: AllNamespaces
webhookdefinitions:
- type: ValidatingAdmissionWebhook (2)
admissionReviewVersions:
- v1beta1
- v1
containerPort: 443
targetPort: 4343
deploymentName: webhook-operator-webhook
failurePolicy: Fail
generateName: vwebhooktest.kb.io
rules:
- apiGroups:
- webhook.operators.coreos.io
apiVersions:
- v1
operations:
- CREATE
- UPDATE
resources:
- webhooktests
sideEffects: None
webhookPath: /validate-webhook-operators-coreos-io-v1-webhooktest
- type: MutatingAdmissionWebhook (3)
admissionReviewVersions:
- v1beta1
- v1
containerPort: 443
targetPort: 4343
deploymentName: webhook-operator-webhook
failurePolicy: Fail
generateName: mwebhooktest.kb.io
rules:
- apiGroups:
- webhook.operators.coreos.io
apiVersions:
- v1
operations:
- CREATE
- UPDATE
resources:
- webhooktests
sideEffects: None
webhookPath: /mutate-webhook-operators-coreos-io-v1-webhooktest
- type: ConversionWebhook (4)
admissionReviewVersions:
- v1beta1
- v1
containerPort: 443
targetPort: 4343
deploymentName: webhook-operator-webhook
generateName: cwebhooktest.kb.io
sideEffects: None
webhookPath: /convert
conversionCRDs:
- webhooktests.webhook.operators.coreos.io (5)
...| 1 | The CRDs targeted by the conversion webhook must exist here. |
| 2 | A validating admission webhook. |
| 3 | A mutating admission webhook. |
| 4 | A conversion webhook. |
| 5 | The spec.PreserveUnknownFields property of each CRD must be set to false or nil. |
Kubernetes documentation:
When deploying an Operator with webhooks using Operator Lifecycle Manager (OLM), you must define the following:
The type field must be set to either ValidatingAdmissionWebhook, MutatingAdmissionWebhook, or ConversionWebhook, or the CSV will be placed in a failed phase.
The CSV must contain a deployment whose name is equivalent to the value supplied in the deploymentName field of the webhookdefinition.
When the webhook is created, OLM ensures that the webhook only acts upon namespaces that match the Operator group that the Operator is deployed in.
OLM is configured to provide each deployment with a single certificate authority (CA). The logic that generates and mounts the CA into the deployment was originally used by the API service lifecycle logic. As a result:
The TLS certificate file is mounted to the deployment at /apis