openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

OSDOCS#14398: Remove docs for the Operator SDK

Browse Source
This commit is contained in:
Michael Ryan Peter
2025-04-17 15:59:01 -04:00
parent 412384f399
commit aa89c4b606
207 changed files with 12 additions and 11279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
_attributes/common-attributes.adoc
View File

@@ -224,10 +224,6 @@ endif::[]
// logical volume manager storage
:lvms-first: Logical Volume Manager (LVM) Storage
:lvms: LVM Storage
//Operator SDK version
:osdk_ver: 1.38.0
//Operator SDK version that shipped with the previous OCP 4.x release
:osdk_ver_n1: 1.36.1
//Version-agnostic OLM
:olm-first: Operator Lifecycle Manager (OLM)
:olm: OLM

82
_topic_maps/_topic_map.yml
View File

@@ -1009,14 +1009,6 @@ Topics:
File: cli-opm-install
- Name: opm CLI reference
File: cli-opm-ref
- Name: Operator SDK
Dir: osdk
Distros: openshift-enterprise,openshift-origin
Topics:
- Name: Installing the Operator SDK CLI
File: cli-osdk-install
- Name: Operator SDK CLI reference
File: cli-osdk-ref
---
Name: Security and compliance
Dir: security
@@ -2007,59 +1999,6 @@ Topics:
Dir: operator_sdk
Distros: openshift-origin,openshift-enterprise
Topics:
- Name: About the Operator SDK
File: osdk-about
- Name: Installing the Operator SDK CLI
File: osdk-installing-cli
- Name: Go-based Operators
Dir: golang
Topics:
- Name: Getting started
File: osdk-golang-quickstart
- Name: Tutorial
File: osdk-golang-tutorial
- Name: Project layout
File: osdk-golang-project-layout
- Name: Updating Go-based projects
File: osdk-golang-updating-projects
- Name: Ansible-based Operators
Dir: ansible
Topics:
- Name: Getting started
File: osdk-ansible-quickstart
- Name: Tutorial
File: osdk-ansible-tutorial
- Name: Project layout
File: osdk-ansible-project-layout
- Name: Updating Ansible-based projects
File: osdk-ansible-updating-projects
- Name: Ansible support
File: osdk-ansible-support
- Name: Kubernetes Collection for Ansible
File: osdk-ansible-k8s-collection
- Name: Using Ansible inside an Operator
File: osdk-ansible-inside-operator
- Name: Custom resource status management
File: osdk-ansible-cr-status
- Name: Helm-based Operators
Dir: helm
Topics:
- Name: Getting started
File: osdk-helm-quickstart
- Name: Tutorial
File: osdk-helm-tutorial
- Name: Project layout
File: osdk-helm-project-layout
- Name: Updating Helm-based projects
File: osdk-helm-updating-projects
- Name: Helm support
File: osdk-helm-support
- Name: Defining cluster service versions (CSVs)
File: osdk-generating-csvs
- Name: Working with bundle images
File: osdk-working-bundle-images
- Name: Complying with pod security admission
File: osdk-complying-with-psa
- Name: Token authentication
Dir: token_auth
Topics:
@@ -2071,27 +2010,6 @@ Topics:
File: osdk-cco-azure
- Name: CCO-based workflow for OLM-managed Operators with GCP Workload Identity
File: osdk-cco-gcp
- Name: Validating Operators using the scorecard
File: osdk-scorecard
- Name: Validating Operator bundles
File: osdk-bundle-validate
- Name: High-availability or single-node cluster detection and support
File: osdk-ha-sno
- Name: Configuring built-in monitoring with Prometheus
File: osdk-monitoring-prometheus
- Name: Configuring leader election
File: osdk-leader-election
- Name: Configuring support for multiple platforms
File: osdk-multi-arch-support
- Name: Object pruning utility
File: osdk-pruning-utility
- Name: Migrating package manifest projects to bundle format
File: osdk-pkgman-to-bundle
- Name: Operator SDK CLI reference
File: osdk-cli-ref
- Name: Migrating to Operator SDK v0.1.0
File: osdk-migrating-to-v0-1-0
Distros: openshift-origin
- Name: Cluster Operators reference
File: operator-reference
- Name: OLM v1

85
_topic_maps/_topic_map_osd.yml
View File

@@ -345,14 +345,6 @@ Topics:
File: cli-opm-install
- Name: opm CLI reference
File: cli-opm-ref
- Name: Operator SDK
Dir: osdk
Distros: openshift-dedicated
Topics:
- Name: Installing the Operator SDK CLI
File: cli-osdk-install
- Name: Operator SDK CLI reference
File: cli-osdk-ref
---
Name: Cluster administration
Dir: osd_cluster_admin
@@ -732,83 +724,6 @@ Topics:
File: olm-cs-podsched
- Name: Troubleshooting Operator issues
File: olm-troubleshooting-operator-issues
- Name: Developing Operators
Dir: operator_sdk
Topics:
- Name: About the Operator SDK
File: osdk-about
- Name: Installing the Operator SDK CLI
File: osdk-installing-cli
- Name: Go-based Operators
Dir: golang
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-golang-quickstart
- Name: Tutorial
File: osdk-golang-tutorial
- Name: Project layout
File: osdk-golang-project-layout
- Name: Updating Go-based projects
File: osdk-golang-updating-projects
- Name: Ansible-based Operators
Dir: ansible
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-ansible-quickstart
- Name: Tutorial
File: osdk-ansible-tutorial
- Name: Project layout
File: osdk-ansible-project-layout
- Name: Updating Ansible-based projects
File: osdk-ansible-updating-projects
- Name: Ansible support
File: osdk-ansible-support
- Name: Kubernetes Collection for Ansible
File: osdk-ansible-k8s-collection
- Name: Using Ansible inside an Operator
File: osdk-ansible-inside-operator
- Name: Custom resource status management
File: osdk-ansible-cr-status
- Name: Helm-based Operators
Dir: helm
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-helm-quickstart
- Name: Tutorial
File: osdk-helm-tutorial
- Name: Project layout
File: osdk-helm-project-layout
- Name: Updating Helm-based projects
File: osdk-helm-updating-projects
- Name: Helm support
File: osdk-helm-support
- Name: Defining cluster service versions (CSVs)
File: osdk-generating-csvs
- Name: Working with bundle images
File: osdk-working-bundle-images
- Name: Complying with pod security admission
File: osdk-complying-with-psa
- Name: Validating Operators using the scorecard
File: osdk-scorecard
- Name: Validating Operator bundles
File: osdk-bundle-validate
- Name: High-availability or single-node cluster detection and support
File: osdk-ha-sno
- Name: Configuring built-in monitoring with Prometheus
File: osdk-monitoring-prometheus
- Name: Configuring leader election
File: osdk-leader-election
- Name: Object pruning utility
File: osdk-pruning-utility
- Name: Migrating package manifest projects to bundle format
File: osdk-pkgman-to-bundle
- Name: Operator SDK CLI reference
File: osdk-cli-ref
- Name: Migrating to Operator SDK v0.1.0
File: osdk-migrating-to-v0-1-0
# ROSA customers can't configure/edit the cluster Operators
# - Name: Cluster Operators reference
# File: operator-reference

85
_topic_maps/_topic_map_rosa.yml
View File

@@ -547,14 +547,6 @@ Topics:
File: cli-opm-install
- Name: opm CLI reference
File: cli-opm-ref
- Name: Operator SDK
Dir: osdk
Distros: openshift-rosa
Topics:
- Name: Installing the Operator SDK CLI
File: cli-osdk-install
- Name: Operator SDK CLI reference
File: cli-osdk-ref
- Name: ROSA CLI
Dir: rosa_cli
Distros: openshift-rosa
@@ -981,83 +973,6 @@ Topics:
File: olm-cs-podsched
- Name: Troubleshooting Operator issues
File: olm-troubleshooting-operator-issues
- Name: Developing Operators
Dir: operator_sdk
Topics:
- Name: About the Operator SDK
File: osdk-about
- Name: Installing the Operator SDK CLI
File: osdk-installing-cli
- Name: Go-based Operators
Dir: golang
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-golang-quickstart
- Name: Tutorial
File: osdk-golang-tutorial
- Name: Project layout
File: osdk-golang-project-layout
- Name: Updating Go-based projects
File: osdk-golang-updating-projects
- Name: Ansible-based Operators
Dir: ansible
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-ansible-quickstart
- Name: Tutorial
File: osdk-ansible-tutorial
- Name: Project layout
File: osdk-ansible-project-layout
- Name: Updating Ansible-based projects
File: osdk-ansible-updating-projects
- Name: Ansible support
File: osdk-ansible-support
- Name: Kubernetes Collection for Ansible
File: osdk-ansible-k8s-collection
- Name: Using Ansible inside an Operator
File: osdk-ansible-inside-operator
- Name: Custom resource status management
File: osdk-ansible-cr-status
- Name: Helm-based Operators
Dir: helm
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-helm-quickstart
- Name: Tutorial
File: osdk-helm-tutorial
- Name: Project layout
File: osdk-helm-project-layout
- Name: Updating Helm-based projects
File: osdk-helm-updating-projects
- Name: Helm support
File: osdk-helm-support
- Name: Defining cluster service versions (CSVs)
File: osdk-generating-csvs
- Name: Working with bundle images
File: osdk-working-bundle-images
- Name: Complying with pod security admission
File: osdk-complying-with-psa
- Name: Validating Operators using the scorecard
File: osdk-scorecard
- Name: Validating Operator bundles
File: osdk-bundle-validate
- Name: High-availability or single-node cluster detection and support
File: osdk-ha-sno
- Name: Configuring built-in monitoring with Prometheus
File: osdk-monitoring-prometheus
- Name: Configuring leader election
File: osdk-leader-election
- Name: Object pruning utility
File: osdk-pruning-utility
- Name: Migrating package manifest projects to bundle format
File: osdk-pkgman-to-bundle
- Name: Operator SDK CLI reference
File: osdk-cli-ref
- Name: Migrating to Operator SDK v0.1.0
File: osdk-migrating-to-v0-1-0
# ROSA customers can't configure/edit the cluster Operators
# - Name: Cluster Operators reference
# File: operator-reference

100
_topic_maps/_topic_map_rosa_hcp.yml
View File

@@ -304,14 +304,6 @@ Topics:
File: cli-opm-install
- Name: opm CLI reference
File: cli-opm-ref
- Name: Operator SDK
Dir: osdk
Distros: openshift-rosa-hcp
Topics:
- Name: Installing the Operator SDK CLI
File: cli-osdk-install
- Name: Operator SDK CLI reference
File: cli-osdk-ref
- Name: ROSA CLI
Dir: rosa_cli
Distros: openshift-rosa-hcp
@@ -752,98 +744,6 @@ Topics:
File: olm-cs-podsched
- Name: Troubleshooting Operator issues
File: olm-troubleshooting-operator-issues
- Name: Developing Operators
Dir: operator_sdk
Topics:
- Name: About the Operator SDK
File: osdk-about
- Name: Installing the Operator SDK CLI
File: osdk-installing-cli
- Name: Go-based Operators
Dir: golang
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-golang-quickstart
- Name: Tutorial
File: osdk-golang-tutorial
- Name: Project layout
File: osdk-golang-project-layout
- Name: Updating Go-based projects
File: osdk-golang-updating-projects
- Name: Ansible-based Operators
Dir: ansible
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-ansible-quickstart
- Name: Tutorial
File: osdk-ansible-tutorial
- Name: Project layout
File: osdk-ansible-project-layout
- Name: Updating Ansible-based projects
File: osdk-ansible-updating-projects
- Name: Ansible support
File: osdk-ansible-support
- Name: Kubernetes Collection for Ansible
File: osdk-ansible-k8s-collection
- Name: Using Ansible inside an Operator
File: osdk-ansible-inside-operator
- Name: Custom resource status management
File: osdk-ansible-cr-status
- Name: Helm-based Operators
Dir: helm
Topics:
# Quick start excluded, because it requires cluster-admin permissions.
# - Name: Getting started
# File: osdk-helm-quickstart
- Name: Tutorial
File: osdk-helm-tutorial
- Name: Project layout
File: osdk-helm-project-layout
- Name: Updating Helm-based projects
File: osdk-helm-updating-projects
- Name: Helm support
File: osdk-helm-support
# - Name: Hybrid Helm Operator <= Tech Preview
# File: osdk-hybrid-helm
# - Name: Updating Hybrid Helm-based projects (Technology Preview)
# File: osdk-hybrid-helm-updating-projects
# - Name: Java-based Operators <= Tech Preview
# Dir: java
# Topics:
# - Name: Getting started
# File: osdk-java-quickstart
# - Name: Tutorial
# File: osdk-java-tutorial
# - Name: Project layout
# File: osdk-java-project-layout
# - Name: Updating Java-based projects
# File: osdk-java-updating-projects
- Name: Defining cluster service versions (CSVs)
File: osdk-generating-csvs
- Name: Working with bundle images
File: osdk-working-bundle-images
- Name: Complying with pod security admission
File: osdk-complying-with-psa
- Name: Validating Operators using the scorecard
File: osdk-scorecard
- Name: Validating Operator bundles
File: osdk-bundle-validate
- Name: High-availability or single-node cluster detection and support
File: osdk-ha-sno
- Name: Configuring built-in monitoring with Prometheus
File: osdk-monitoring-prometheus
- Name: Configuring leader election
File: osdk-leader-election
- Name: Object pruning utility
File: osdk-pruning-utility
- Name: Migrating package manifest projects to bundle format
File: osdk-pkgman-to-bundle
- Name: Operator SDK CLI reference
File: osdk-cli-ref
- Name: Migrating to Operator SDK v0.1.0
File: osdk-migrating-to-v0-1-0
# ROSA customers can't configure/edit the cluster Operators
# - Name: Cluster Operators reference
# File: operator-reference

195
_unused_topics/osdk-updating-v1101-to-v1160.adoc
View File

@@ -1,195 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-upgrading-projects.adoc
:osdk_ver: v1.16.0
:osdk_ver_n1: v1.10.1
:_mod-docs-content-type: PROCEDURE
[id="osdk-upgrading-v1101-to-v1160_{context}"]
= Updating projects for Operator SDK {osdk_ver}
The following procedure updates an existing Operator project for compatibility with {osdk_ver}.
[IMPORTANT]
====
* Operator SDK v1.16.0 supports Kubernetes 1.22.
* Many deprecated `v1beta1` APIs were removed in Kubernetes 1.22, including `sigs.k8s.io/controller-runtime v0.10.0` and `controller-gen v0.7`.
* Updating projects to Kubernetes 1.22 is a breaking change if you need to scaffold `v1beta1` APIs for custom resource definitions (CRDs) or webhooks to publish your project into older cluster versions.
See link:https://docs.openshift.com/container-platform/4.9/release_notes/ocp-4-9-release-notes.html#ocp-4-9-osdk-k8s-api-bundle-validate[Validating bundle manifests for APIs removed from Kubernetes 1.22] and link:https://docs.openshift.com/container-platform/4.9/release_notes/ocp-4-9-release-notes.html#ocp-4-9-removed-kube-1-22-apis[Beta APIs removed from Kubernetes 1.22] for more information about changes introduced in Kubernetes 1.22.
====
.Prerequisites
* Operator SDK {osdk_ver} installed.
* An Operator project created or maintained with Operator SDK {osdk_ver_n1}.
.Procedure
. Add the `protocol` field in the `config/default/manager_auth_proxy_patch.yaml` and `config/rbac/auth_proxy_service.yaml` files:
+
[source,diff]
----
...
ports:
- containerPort: 8443
+ protocol: TCP
name: https
----
. Make the following changes to the `config/manager/manager.yaml` file:
.. Increase the CPU and memory resource limits:
+
[source,diff]
----
resources:
limits:
- cpu: 100m
- memory: 30Mi
+ cpu: 200m
+ memory: 100Mi
----
.. Add an annotation to specify the default container manager:
+
[source,yaml]
----
...
template:
metadata:
annotations:
kubectl.kubernetes.io/default-container: manager
...
----
. Add `PHONY` targets to all of the targets in your `Makefile` file.
. For Go-based Operator projects, make the following changes:
.. Install the `setup-envtest` binary.
.. Change your `go.mod` file to update the dependencies:
+
[source,golang]
----
k8s.io/api v0.22.1
k8s.io/apimachinery v0.22.1
k8s.io/client-go v0.22.1
sigs.k8s.io/controller-runtime v0.10.0
----
.. Run the `go mod tidy` command to download the dependencies:
+
[source,terminal]
----
$ go mod tidy
----
.. Make the following changes to your `Makefile` file:
+
[source,diff]
----
...
+ ENVTEST_K8S_VERSION = 1.22
test: manifests generate fmt vet envtest ## Run tests.
- go test ./... -coverprofile cover.out
+ KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out
...
- $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+ $(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
...
# Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
- CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false"
...
- admissionReviewVersions={v1,v1beta1}
+ admissionReviewVersions=v1
...
+ ifndef ignore-not-found
+ ignore-not-found = false
+ endif
##@ Deployment
...
- sh kubectl delete -f -
+ sh kubectl delete --ignore-not-found=$(ignore-not-found) -f -
----
.. Run the `make manifest` command to generate your manifests with the updated version of Kubernetes:
+
[source,terminal]
----
$ make manifest
----
. For Ansible-based Operator projects, make the following changes:
+
.. Change your `requirements.yml` file to include the following:
... Replace the `community.kubernetes` collection with the `kubernetes.core` collection:
+
[source,yaml]
----
...
- name: kubernetes.core
version: "2.2.0"
...
----
... Update the `operator_sdk.util` utility from version `0.2.0` to `0.3.1`:
+
[source,yaml]
----
...
- name: operator_sdk.util
version: "0.3.1"
----
.. Verify the default resource limits in the `config/manager/manager.yaml` file:
+
[source,yaml]
----
...
# TODO(user): Configure the resources accordingly based on the project requirements.
# More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
resources:
limits:
cpu: 500m
memory: 768Mi
requests:
cpu: 10m
memory: 256Mi
----
+
[IMPORTANT]
====
Operator SDK scaffolds these values as a reasonable default setting. Operator authors should set and optimize resource limits based on the requirements of their project.
====
.. Optional: Make the following changes if you want to run your Ansible-based Operator locally by using the `make run` command:
... Change the run target in the `Makefile` file:
+
[source,terminal]
----
ANSIBLE_ROLES_PATH="$(ANSIBLE_ROLES_PATH):$(shell pwd)/roles" $(ANSIBLE_OPERATOR) run
----
... Update the local version of `ansible-runner` to 2.0.2 or later.
+
[IMPORTANT]
====
As of version 2.0, the `ansible-runner` tool includes changes in the command signature that are not compatible with earlier versions.
====
:!osdk_ver:
:!osdk_ver_n1:

130
_unused_topics/osdk-updating-v125-to-v128.adoc
View File

@@ -1,130 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-updating-projects.adoc
// * operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc
// * operators/operator_sdk/helm/osdk-helm-updating-projects.adoc
// * operators/operator_sdk/helm/
ifeval::["{context}" == "osdk-golang-updating-projects"]
:golang:
:type: Go
endif::[]
ifeval::["{context}" == "osdk-ansible-updating-projects"]
:ansible:
:type: Ansible
endif::[]
ifeval::["{context}" == "osdk-helm-updating-projects"]
:helm:
:type: Helm
endif::[]
:_mod-docs-content-type: PROCEDURE
[id="osdk-upgrading-projects_{context}"]
= Updating {type}-based Operator projects for Operator SDK {osdk_ver}
The following procedure updates an existing {type}-based Operator project for compatibility with {osdk_ver}.
.Prerequisites
* Operator SDK {osdk_ver} installed
* An Operator project created or maintained with Operator SDK {osdk_ver_n1}
.Procedure
ifdef::helm[]
* Find the `ose-kube-rbac-proxy` pull spec in the following files, and update the image tag to `v4.14`:
endif::[]
ifdef::ansible,golang[]
. Find the `ose-kube-rbac-proxy` pull spec in the following files, and update the image tag to `v4.14`:
endif::[]
+
--
* `config/default/manager_auth_proxy_patch.yaml`
* `bundle/manifests/memcached-operator.clusterserviceversion.yaml`
--
+
[source,yaml]
----
…
containers:
- name: kube-rbac-proxy
image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.14 <1>
…
----
<1> Update the tag version from `v4.13` to `v4.14`.
ifdef::ansible[]
. Update your Makefile's `run` target to the following:
+
[source,make]
----
.PHONY: run
ANSIBLE_ROLES_PATH?="$(shell pwd)/roles"
run: ansible-operator ## Run against the configured Kubernetes cluster in ~/.kube/config
$(ANSIBLE_OPERATOR) run
----
. To upgrade the `kubernetes.core` collection to v2.4.0, replace the following in your project's `requirements.yaml` file:
+
[source,yaml]
----
- name: kubernetes.core
version: "2.3.1"
----
+
with:
+
[source,yaml]
----
- name: kubernetes.core
version: "2.4.0"
----
endif::[]
ifdef::golang[]
. Modify your `go.mod` file to include the following dependencies and updated versions:
+
[source,go]
----
k8s.io/api v0.26.2
k8s.io/apiextensions-apiserver v0.26.2
k8s.io/apimachinery v0.26.2
k8s.io/cli-runtime v0.26.2
k8s.io/client-go v0.26.2
k8s.io/kubectl v0.26.2
sigs.k8s.io/controller-runtime v0.14.5
sigs.k8s.io/controller-tools v0.11.3
sigs.k8s.io/kubebuilder/v3 v3.9.1
----
. Download the latest dependencies by running the following command:
+
[source,terminal]
----
$ go mod tidy
----
. Modify your Makefile with the following changes:
.. Change the `ENVTEST_K8S_VERSION` field from `1.26` to `1.27`.
.. Change the `build` target from `generate fmt vet` to `manifests generate fmt vet`:
+
[source,diff]
----
- build: generate fmt vet ## Build manager binary.
+ build: manifests generate fmt vet ## Build manager binary.
----
endif::[]
ifeval::["{context}" == "osdk-golang-updating-projects"]
:!golang:
:!type:
endif::[]
ifeval::["{context}" == "osdk-ansible-updating-projects"]
:!ansible:
:!type:
endif::[]
ifeval::["{context}" == "osdk-helm-updating-projects"]
:!helm:
:!type:
endif::[]

39
_unused_topics/osdk-upgrading-v180-to-v1101.adoc
View File

@@ -1,39 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-upgrading-projects.adoc
:osdk_ver: v1.10.1
:osdk_ver_n1: v1.8.0
:_mod-docs-content-type: PROCEDURE
[id="osdk-upgrading-v180-to-v1101_{context}"]
= Upgrading projects for Operator SDK {osdk_ver}
The following upgrade steps must be performed to upgrade an existing Operator project for compatibility with {osdk_ver}.
.Prerequisites
- Operator SDK {osdk_ver} installed
- Operator project that was previously created or maintained with Operator SDK {osdk_ver_n1}
.Procedure
* For Ansible-based Operator projects, update the command in the `Set pull policy` section of the `molecule/default/prepare.yml` file:
+
.`molecule/default/prepare.yml` file diff
[%collapsible]
====
[source,diff]
----
- name: Set pull policy
- command: '{{ "{{ kustomize }}" }} edit add patch pull_policy/{{ "{{ operator_pull_policy }}" }}.yaml'
+ command: '{{ "{{ kustomize }}" }} edit add patch --path pull_policy/{{ "{{ operator_pull_policy }}" }}.yaml'
----
====
+
Ansible projects are now scaffolded with Kustomize version 3.8.7. This version of Kustomize requires that the path to patch files be provided with the `--path` flag in the `add patch` command.
Your Operator project is now compatible with Operator SDK {osdk_ver}.
:!osdk_ver:
:!osdk_ver_n1:

6
architecture/control-plane.adoc
View File

@@ -54,8 +54,8 @@ include::modules/arch-olm-operators.adoc[leveloffset=+2]
[role="_additional-resources"]
.Additional resources
* For more details on running add-on Operators in {product-title}, see the _Operators_ guide sections on xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager (OLM)] and xref:../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[OperatorHub].
* For more details on the Operator SDK, see xref:../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators].
* xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager (OLM) concepts and resources]
* xref:../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub].
include::modules/etcd-overview.adoc[leveloffset=+1]
@@ -71,4 +71,4 @@ ifndef::openshift-dedicated,openshift-rosa[]
.Additional resources
* xref:../scalability_and_performance/recommended-performance-scale-practices/recommended-etcd-practices.adoc#recommended-etcd-practices[Recommended etcd practices]
* xref:../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backing-up-etcd[Backing up etcd]
endif::openshift-dedicated,openshift-rosa[]
endif::openshift-dedicated,openshift-rosa[]

5
cli_reference/index.adoc
View File

@@ -15,7 +15,6 @@ such as the following:
* Managing clusters
* Building, deploying, and managing applications
* Managing deployment processes
* Developing Operators
* Creating and maintaining Operator catalogs
ifndef::openshift-rosa[]
@@ -60,8 +59,6 @@ using the terminal. Unlike the web console, it allows the user to work directly
* xref:../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[opm CLI]: The `opm` CLI tool helps the Operator developers and cluster administrators to create and maintain the catalogs of Operators from the terminal.
* xref:../cli_reference/osdk/cli-osdk-install.adoc#cli-osdk-install[Operator SDK]: The Operator SDK, a component of the Operator Framework, provides a CLI tool that Operator developers can use to build, test, and deploy an Operator from the terminal. It simplifies the process of building Kubernetes-native applications, which can require deep, application-specific operational knowledge.
ifdef::openshift-rosa,openshift-rosa-hcp[]
* xref:../cli_reference/rosa_cli/rosa-get-started-cli.adoc#rosa-get-started-cli[ROSA CLI (`rosa`)]: Use the `rosa` CLI to create, update, manage, and delete ROSA clusters and resources.
endif::openshift-rosa,openshift-rosa-hcp[]
endif::openshift-rosa,openshift-rosa-hcp[]

5
cli_reference/opm/cli-opm-install.adoc
View File

@@ -13,8 +13,7 @@ ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
.Additional resources
* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging format] for more information about the bundle format.
* To create a bundle image using the Operator SDK, see
xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-working-bundle-images[Working with bundle images].
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
include::modules/olm-installing-opm.adoc[leveloffset=+1]
@@ -24,4 +23,4 @@ ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
== Additional resources
* See xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs[Managing custom catalogs] for `opm` procedures including creating, updating, and pruning catalogs.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]

1
cli_reference/osdk/_attributes
View File

@@ -1 +0,0 @@
../../_attributes/

25
cli_reference/osdk/cli-osdk-install.adoc
View File

@@ -1,25 +0,0 @@
:_mod-docs-content-type: ASSEMBLY
[id="cli-osdk-install"]
= Installing the Operator SDK CLI
include::_attributes/common-attributes.adoc[]
:context: cli-osdk-install
toc::[]
The Operator SDK provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. You can install the Operator SDK CLI on your workstation so that you are prepared to start authoring your own Operators.
include::snippets/osdk-deprecation.adoc[]
Operator authors with cluster administrator access to a Kubernetes-based cluster, such as {product-title}, can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, Java, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work.
ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK.
[NOTE]
====
{product-title} {product-version} supports Operator SDK {osdk_ver}.
====
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
include::modules/osdk-installing-cli-linux-macos.adoc[leveloffset=+1]
include::modules/osdk-installing-cli-macos.adoc[leveloffset=+1]

56
cli_reference/osdk/cli-osdk-ref.adoc
View File

@@ -1,56 +0,0 @@
:_mod-docs-content-type: ASSEMBLY
[id="cli-osdk-ref"]
= Operator SDK CLI reference
include::_attributes/common-attributes.adoc[]
:context: cli-osdk-ref
toc::[]
The Operator SDK command-line interface (CLI) is a development kit designed to make writing Operators easier.
include::snippets/osdk-deprecation.adoc[]
.Operator SDK CLI syntax
[source,terminal]
----
$ operator-sdk <command> [<subcommand>] [<argument>] [<flags>]
----
ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
include::modules/osdk-cli-ref-bundle.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-cleanup.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-completion.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-create.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-generate.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-generate-bundle.adoc[leveloffset=+2]
ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
[role="_additional-resources"]
.Additional resources
* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes using the `make bundle` command to call the `generate bundle` subcommand.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
include::modules/osdk-cli-ref-generate-kustomize.adoc[leveloffset=+2]
include::modules/osdk-cli-ref-init.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-run.adoc[leveloffset=+1]
include::modules/osdk-cli-ref-run-bundle.adoc[leveloffset=+2]
ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
[role="_additional-resources"]
.Additional resources
* See xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership] for details on possible install modes.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
include::modules/osdk-cli-ref-run-bundle-upgrade.adoc[leveloffset=+2]
include::modules/osdk-cli-ref-scorecard.adoc[leveloffset=+1]
ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
[role="_additional-resources"]
.Additional resources
* See xref:../../operators/operator_sdk/osdk-scorecard.adoc#osdk-scorecard[Validating Operators using the scorecard tool] for details about running the scorecard tool.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]

1
cli_reference/osdk/images
View File

@@ -1 +0,0 @@
../../images/

1
cli_reference/osdk/modules
View File

@@ -1 +0,0 @@
../../modules/

1
cli_reference/osdk/snippets
View File

@@ -1 +0,0 @@
../../snippets/

2
contributing_to_docs/term_glossary.adoc
View File

@@ -512,8 +512,6 @@ Operator that packages an application.
.Examples of correct usage
====
Install the etcd Operator.
Build an Operator using the Operator SDK.
====
See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for

8
disconnected/mirroring/installing-mirroring-installation-images.adoc
View File

@@ -119,16 +119,8 @@ $ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json
include::modules/olm-mirroring-catalog-extracting.adoc[leveloffset=+2]
include::modules/olm-mirroring-catalog-colocated.adoc[leveloffset=+3]
[role="_additional-resources"]
.Additional resources
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators]
include::modules/olm-mirroring-catalog-airgapped.adoc[leveloffset=+3]
[role="_additional-resources"]
.Additional resources
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators]
include::modules/olm-mirroring-catalog-manifests.adoc[leveloffset=+2]
include::modules/olm-mirroring-catalog-post.adoc[leveloffset=+2]

3
disconnected/using-olm.adoc
View File

@@ -39,7 +39,6 @@ Infrastructure features:: Disconnected
.Additional resources
* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red{nbsp}Hat-provided Operator catalogs]
* xref:../operators/operator_sdk/osdk-generating-csvs.adoc#olm-enabling-operator-for-restricted-network_osdk-generating-csvs[Enabling your Operator for restricted network environments]
[id="olm-restricted-network-prereqs"]
== Prerequisites
@@ -76,4 +75,4 @@ include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1]
[id="next-steps_olm-restricted-networks"]
== Next steps
* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]
* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]

2
extensions/catalogs/managing-catalogs.adoc
View File

@@ -15,8 +15,6 @@ _File-based catalogs_ are the latest iteration of the catalog format in Operator
[IMPORTANT]
====
Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. As a result, Operators are unable to use removed APIs starting with the version of {product-title} that uses the Kubernetes version that removed the API.
If your cluster is using custom catalogs, see xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-control-compat_osdk-working-bundle-images[Controlling Operator compatibility with {product-title} versions] for more details about how Operator authors can update their projects to help avoid workload issues and prevent incompatible upgrades.
====
include::modules/olmv1-about-catalogs.adoc[leveloffset=+1]

3
getting_started/openshift-overview.adoc
View File

@@ -76,9 +76,6 @@ describes an application that can be deployed using the Helm CLI.
* **xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Understand Operators]**: Operators are the preferred method for creating on-cluster applications for {product-title} {product-version}. Learn about the Operator Framework and how to deploy applications using installed Operators into your projects.
* **xref:../operators/operator_sdk/osdk-about.adoc#osdk-about[Develop Operators]**: Operators are the preferred method for creating on-cluster applications for {product-title} {product-version}. Learn the workflow for building, testing, and deploying Operators. Then, create your own Operators based on xref:../operators/operator_sdk/ansible/osdk-ansible-support.adoc#osdk-ansible-support[Ansible] or
xref:../operators/operator_sdk/helm/osdk-helm-support.adoc#osdk-helm-support[Helm], or configure xref:../operators/operator_sdk/osdk-monitoring-prometheus.adoc#osdk-monitoring-prometheus[built-in Prometheus monitoring] using the Operator SDK.
* **xref:../rest_api/overview/index.adoc#api-index[REST API reference]**: Learn about {product-title} application programming interface endpoints.
=== For administrators

2
modules/arch-olm-operators.adoc
View File

@@ -32,8 +32,6 @@ All Operators listed in the Operator Hub marketplace should be available for ins
====
endif::openshift-dedicated,openshift-rosa[]
Developers can use the Operator SDK to help author custom Operators that take advantage of OLM features, as well. Their Operator can then be bundled and added to a custom catalog source, which can be added to a cluster and made available to users.
[NOTE]
====
OLM does not manage the cluster Operators that comprise the {product-title} architecture.

443
modules/building-memcached-operator-using-osdk.adoc
View File

@@ -1,443 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-getting-started.adoc
[id="building-memcached-operator-using-osdk_{context}"]
= Building a Go-based Operator using the Operator SDK
This procedure walks through an example of building a simple Memcached Operator using tools and libraries provided by the SDK.
.Prerequisites
- Operator SDK CLI installed on the development workstation
- Operator Lifecycle Manager (OLM) installed on a Kubernetes-based cluster (v1.8
or above to support the `apps/v1beta2` API group), for example {product-title} {product-version}
- Access to the cluster using an account with `cluster-admin` permissions
- OpenShift CLI (`oc`) v{product-version}+ installed
.Procedure
. *Create a new project.*
+
Use the CLI to create a new `memcached-operator` project:
+
[source,terminal]
----
$ mkdir -p $GOPATH/src/github.com/example-inc/
----
+
[source,terminal]
----
$ cd $GOPATH/src/github.com/example-inc/
----
+
[source,terminal]
----
$ operator-sdk new memcached-operator
----
+
[source,terminal]
----
$ cd memcached-operator
----
. *Add a new custom resource definition (CRD).*
.. Use the CLI to add a new CRD API called `Memcached`, with `APIVersion` set to `cache.example.com/v1apha1` and `Kind` set to `Memcached`:
+
[source,terminal]
----
$ operator-sdk add api \
--api-version=cache.example.com/v1alpha1 \
--kind=Memcached
----
+
This scaffolds the Memcached resource API under `pkg/apis/cache/v1alpha1/`.
.. Modify the spec and status of the `Memcached` custom resource (CR) at the `pkg/apis/cache/v1alpha1/memcached_types.go` file:
+
[source,go]
----
type MemcachedSpec struct {
// Size is the size of the memcached deployment
Size int32 `json:"size"`
}
type MemcachedStatus struct {
// Nodes are the names of the memcached pods
Nodes []string `json:"nodes"`
}
----
.. After modifying the `*_types.go` file, always run the following command to update the generated code for that resource type:
+
[source,terminal]
----
$ operator-sdk generate k8s
----
. *Optional: Add custom validation to your CRD.*
+
OpenAPI v3.0 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached CR when it is created or updated.
+
Additionally, a `pkg/apis/<group>/<version>/zz_generated.openapi.go` file is generated. This file contains the Go representation of this validation block if the `+k8s:openapi-gen=true annotation` is present above the `Kind` type declaration, which is present by default. This auto-generated code is the OpenAPI model of your Go `Kind` type, from which you can create a full OpenAPI Specification and generate a client.
+
As an Operator author, you can use Kubebuilder markers (annotations) to configure custom validations for your API. These markers must always have a `+kubebuilder:validation` prefix. For example, adding an enum-type specification can be done by adding the following marker:
+
[source,go]
----
// +kubebuilder:validation:Enum=Lion;Wolf;Dragon
type Alias string
----
+
Usage of markers in API code is discussed in the Kubebuilder link:https://book.kubebuilder.io/reference/generating-crd.html[Generating CRDs] and link:https://book.kubebuilder.io/reference/markers.html[Markers for Config/Code Generation] documentation. A full list of OpenAPIv3 validation markers is also available in the Kubebuilder link:https://book.kubebuilder.io/reference/markers/crd-validation.html[CRD Validation] documentation.
+
If you add any custom validations, run the following command to update the OpenAPI validation section in the `deploy/crds/cache.example.com_memcacheds_crd.yaml` file for the CRD:
+
[source,terminal]
----
$ operator-sdk generate crds
----
+
.Example generated YAML
[source,yaml]
----
spec:
validation:
openAPIV3Schema:
properties:
spec:
properties:
size:
format: int32
type: integer
----
. *Add a new controller.*
.. Add a new controller to the project to watch and reconcile the `Memcached` resource:
+
[source,terminal]
----
$ operator-sdk add controller \
--api-version=cache.example.com/v1alpha1 \
--kind=Memcached
----
+
This scaffolds a new controller implementation under `pkg/controller/memcached/`.
.. For this example, replace the generated controller file `pkg/controller/memcached/memcached_controller.go` with the link:https://github.com/operator-framework/operator-sdk/blob/master/example/memcached-operator/memcached_controller.go.tmpl[example implementation].
+
The example controller executes the following reconciliation logic for each `Memcached` resource:
+
--
* Create a Memcached deployment if it does not exist.
* Ensure that the Deployment size is the same as specified by the `Memcached` CR spec.
* Update the `Memcached` resource status with the names of the Memcached pods.
--
+
The next two sub-steps inspect how the controller watches resources and how the reconcile loop is triggered. You can skip these steps to go directly to building and running the Operator.
.. Inspect the controller implementation at the `pkg/controller/memcached/memcached_controller.go` file to see how the controller watches resources.
+
The first watch is for the `Memcached` type as the primary resource. For each add, update, or delete event, the reconcile loop is sent a reconcile `Request` (a `<namespace>:<name>` key) for that `Memcached` object:
+
[source,go]
----
err := c.Watch(
&source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{})
----
+
The next watch is for `Deployment` objects, but the event handler maps each event to a reconcile `Request` for the owner of the deployment. In this case, this is the `Memcached` object for which the deployment was created. This allows the controller to watch deployments as a secondary resource:
+
[source,go]
----
err := c.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForOwner{
IsController: true,
OwnerType: &cachev1alpha1.Memcached{},
})
----
.. Every controller has a `Reconciler` object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the `Request` argument which is a `<namespace>:<name>` key used to lookup the primary resource object, `Memcached`, from the cache:
+
[source,go]
----
func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) {
// Lookup the Memcached instance for this reconcile request
memcached := &cachev1alpha1.Memcached{}
err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
...
}
----
+
Based on the return value of the `Reconcile()` function, the reconcile `Request` might be requeued, and the loop might be triggered again:
+
[source,go]
----
// Reconcile successful - don't requeue
return reconcile.Result{}, nil
// Reconcile failed due to error - requeue
return reconcile.Result{}, err
// Requeue for any reason other than error
return reconcile.Result{Requeue: true}, nil
----
[id="building-memcached-operator-using-osdk-build-and-run_{context}"]
. *Build and run the Operator.*
.. Before running the Operator, the CRD must be registered with the Kubernetes API server:
+
[source,terminal]
----
$ oc create \
-f deploy/crds/cache_v1alpha1_memcached_crd.yaml
----
.. After registering the CRD, there are two options for running the Operator:
+
--
* As a Deployment inside a Kubernetes cluster
* As Go program outside a cluster
--
+
Choose one of the following methods.
... _Option A:_ Running as a deployment inside the cluster.
.... Build the `memcached-operator` image and push it to a registry:
+
[source,terminal]
----
$ operator-sdk build quay.io/example/memcached-operator:v0.0.1
----
.... The deployment manifest is generated at `deploy/operator.yaml`. Update the deployment image as follows since the default is just a placeholder:
+
[source,terminal]
----
$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml
----
.... Ensure you have an account on link:https://quay.io[Quay.io] for the next step, or substitute your preferred container registry. On the registry, link:https://quay.io/new/[create a new public image] repository named `memcached-operator`.
.... Push the image to the registry:
+
[source,terminal]
----
$ podman push quay.io/example/memcached-operator:v0.0.1
----
.... Set up RBAC and create the `memcached-operator` manifests:
+
[source,terminal]
----
$ oc create -f deploy/role.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/role_binding.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/service_account.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/operator.yaml
----
.... Verify that the `memcached-operator` deploy is up and running:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
memcached-operator 1 1 1 1 1m
----
... _Option B:_ Running locally outside the cluster.
+
This method is preferred during development cycle to deploy and test faster.
+
Run the Operator locally with the default Kubernetes configuration file present at `$HOME/.kube/config`:
+
[source,terminal]
----
$ operator-sdk run --local --namespace=default
----
+
You can use a specific `kubeconfig` using the flag `--kubeconfig=<path/to/kubeconfig>`.
. *Verify that the Operator can deploy a Memcached application* by creating a `Memcached` CR.
.. Create the example `Memcached` CR that was generated at `deploy/crds/cache_v1alpha1_memcached_cr.yaml`.
.. View the file:
+
[source,terminal]
----
$ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml
----
+
.Example output
[source,terminal]
----
apiVersion: "cache.example.com/v1alpha1"
kind: "Memcached"
metadata:
name: "example-memcached"
spec:
size: 3
----
.. Create the object:
+
[source,terminal]
----
$ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml
----
.. Ensure that `memcached-operator` creates the deployment for the CR:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
memcached-operator 1 1 1 1 2m
example-memcached 3 3 3 3 1m
----
.. Check the pods and CR to confirm the CR status is updated with the pod names:
+
[source,terminal]
----
$ oc get pods
----
+
.Example output
[source,terminal]
----
NAME READY STATUS RESTARTS AGE
example-memcached-6fd7c98d8-7dqdr 1/1 Running 0 1m
example-memcached-6fd7c98d8-g5k7v 1/1 Running 0 1m
example-memcached-6fd7c98d8-m7vn7 1/1 Running 0 1m
memcached-operator-7cc7cfdf86-vvjqk 1/1 Running 0 2m
----
+
[source,terminal]
----
$ oc get memcached/example-memcached -o yaml
----
+
.Example output
[source,terminal]
----
apiVersion: cache.example.com/v1alpha1
kind: Memcached
metadata:
clusterName: ""
creationTimestamp: 2018-03-31T22:51:08Z
generation: 0
name: example-memcached
namespace: default
resourceVersion: "245453"
selfLink: /apis/cache.example.com/v1alpha1/namespaces/default/memcacheds/example-memcached
uid: 0026cc97-3536-11e8-bd83-0800274106a1
spec:
size: 3
status:
nodes:
- example-memcached-6fd7c98d8-7dqdr
- example-memcached-6fd7c98d8-g5k7v
- example-memcached-6fd7c98d8-m7vn7
----
. *Verify that the Operator can manage a deployed Memcached application* by updating the size of the deployment.
.. Change the `spec.size` field in the `memcached` CR from `3` to `4`:
+
[source,terminal]
----
$ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml
----
+
.Example output
[source,terminal]
----
apiVersion: "cache.example.com/v1alpha1"
kind: "Memcached"
metadata:
name: "example-memcached"
spec:
size: 4
----
.. Apply the change:
+
[source,terminal]
----
$ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml
----
.. Confirm that the Operator changes the deployment size:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
example-memcached 4 4 4 4 5m
----
. *Clean up the resources:*
+
[source,terminal]
----
$ oc delete -f deploy/crds/cache_v1alpha1_memcached_cr.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/crds/cache_v1alpha1_memcached_crd.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/operator.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/role.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/role_binding.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/service_account.yaml
----
[role="_additional-resources"]
.Additional resources
* For more information about OpenAPI v3.0 validation schemas in CRDs, refer to the link:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation].

45
modules/creating-new-osdk-v0-1-0-project.adoc
View File

@@ -1,45 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc
:_mod-docs-content-type: PROCEDURE
[id="creating-new-operator-sdk-v0-1-0-project_{context}"]
= Creating a new Operator SDK v0.1.0 project
Rename your Operator SDK v0.0.x project and create a new v0.1.0 project in its
place.
.Prerequisites
- Operator SDK v0.1.0 CLI installed on the development workstation
- `memcached-operator` project previously deployed using an earlier version of
Operator SDK
.Procedure
. Ensure the SDK version is v0.1.0:
+
[source,terminal]
----
$ operator-sdk --version
operator-sdk version 0.1.0
----
. Create a new project:
+
[source,terminal]
----
$ mkdir -p $GOPATH/src/github.com/example-inc/
$ cd $GOPATH/src/github.com/example-inc/
$ mv memcached-operator old-memcached-operator
$ operator-sdk new memcached-operator --skip-git-init
$ ls
memcached-operator old-memcached-operator
----
. Copy `.git` from the old project:
+
[source,terminal]
----
$ cp -rf old-memcached-operator/.git memcached-operator/.git
----

59
modules/migrating-custom-types-pkg-apis.adoc
View File

@@ -1,59 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc
:_mod-docs-content-type: PROCEDURE
[id="migrating-custom-types-from-pkg-apis_{context}"]
= Migrating custom types from pkg/apis
Migrate your project's custom types to the updated Operator SDK v0.1.0 usage.
.Prerequisites
- Operator SDK v0.1.0 CLI installed on the development workstation
- `memcached-operator` project previously deployed using an earlier version of
Operator SDK
- New project created using Operator SDK v0.1.0
.Procedure
. *Create the scaffold API for custom types.*
.. Create the API for your custom resource (CR) in the new project with
`operator-sdk add api --api-version=<apiversion> --kind=<kind>`:
+
[source,terminal]
----
$ cd memcached-operator
$ operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=Memcached
$ tree pkg/apis
pkg/apis/
├── addtoscheme_cache_v1alpha1.go
├── apis.go
└── cache
└── v1alpha1
├── doc.go
├── memcached_types.go
├── register.go
└── zz_generated.deepcopy.go
----
.. Repeat the previous command for as many custom types as you had defined in your
old project. Each type will be defined in the file
`pkg/apis/<group>/<version>/<kind>_types.go`.
. *Copy the contents of the type.*
.. Copy the `Spec` and `Status` contents of the
`pkg/apis/<group>/<version>/types.go` file from the old project to the new
project's `pkg/apis/<group>/<version>/<kind>_types.go` file.
.. Each `<kind>_types.go` file has an `init()` function. Be sure not to remove that
since that registers the type with the Manager's scheme:
+
[source,golang]
----
func init() {
SchemeBuilder.Register(&Memcached{}, &MemcachedList{})
----

313
modules/migrating-reconcile-code.adoc
View File

@@ -1,313 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc
:_mod-docs-content-type: PROCEDURE
[id="migrating-reconcile-code_{context}"]
= Migrating reconcile code
Migrate your project's reconcile code to the update Operator SDK v0.1.0 usage.
.Prerequisites
- Operator SDK v0.1.0 CLI installed on the development workstation
- `memcached-operator` project previously deployed using an earlier version of
Operator SDK
- Custom types migrated from `pkg/apis/`
.Procedure
. *Add a controller to watch your CR.*
+
In v0.0.x projects, resources to be watched were previously defined in
`cmd/<operator-name>/main.go`:
+
[source,golang]
----
sdk.Watch("cache.example.com/v1alpha1", "Memcached", "default", time.Duration(5)*time.Second)
----
+
For v0.1.0 projects, you must define a
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller[Controller]
to watch resources:
.. Add a controller to watch your CR type with `operator-sdk add controller --api-version=<apiversion> --kind=<kind>`.
+
[source,terminal]
----
$ operator-sdk add controller --api-version=cache.example.com/v1alpha1 --kind=Memcached
$ tree pkg/controller
pkg/controller/
├── add_memcached.go
├── controller.go
└── memcached
└── memcached_controller.go
----
.. Inspect the `add()` function in your `pkg/controller/<kind>/<kind>_controller.go` file:
+
[source,golang]
----
import (
cachev1alpha1 "github.com/example-inc/memcached-operator/pkg/apis/cache/v1alpha1"
...
)
func add(mgr manager.Manager, r reconcile.Reconciler) error {
c, err := controller.New("memcached-controller", mgr, controller.Options{Reconciler: r})
// Watch for changes to the primary resource Memcached
err = c.Watch(&source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{})
// Watch for changes to the secondary resource pods and enqueue reconcile requests for the owner Memcached
err = c.Watch(&source.Kind{Type: &corev1.Pod{}}, &handler.EnqueueRequestForOwner{
IsController: true,
OwnerType: &cachev1alpha1.Memcached{},
})
}
----
+
Remove the second `Watch()` or modify it to watch a secondary resource type that
is owned by your CR.
+
Watching multiple resources lets you trigger the reconcile loop for multiple
resources relevant to your application. See the
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Watching_and_EventHandling[watching and eventhandling]
documentation and the Kubernetes
link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/controllers.md[controller conventions]
documentation for more details.
+
If your Operator is watching more than one CR type, you can do one of the
following depending on your application:
+
--
** If the CR is owned by your primary CR, watch it as a secondary resource in
the same controller to trigger the reconcile loop for the primary resource.
+
[source,golang]
----
// Watch for changes to the primary resource Memcached
err = c.Watch(&source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{})
// Watch for changes to the secondary resource AppService and enqueue reconcile requests for the owner Memcached
err = c.Watch(&source.Kind{Type: &appv1alpha1.AppService{}}, &handler.EnqueueRequestForOwner{
IsController: true,
OwnerType: &cachev1alpha1.Memcached{},
})
----
** Add a new controller to watch and reconcile the CR independently of the other CR.
+
[source,terminal]
----
$ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService
----
+
[source,golang]
----
// Watch for changes to the primary resource AppService
err = c.Watch(&source.Kind{Type: &appv1alpha1.AppService{}}, &handler.EnqueueRequestForObject{})
----
--
. *Copy and modify reconcile code from `pkg/stub/handler.go`.*
+
In a v0.1.0 project, the reconcile code is defined in the `Reconcile()` method
of a controller's
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler[Reconciler].
This is similar to the `Handle()` function in the older project. Note the
difference in the arguments and return values:
+
--
- Reconcile:
+
[source,golang]
----
func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error)
----
- Handle:
+
[source,golang]
----
func (h *Handler) Handle(ctx context.Context, event sdk.Event) error
----
--
+
Instead of receiving an `sdk.Event` (with the object), the `Reconcile()`
function receives a
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request[Request]
(`Name`/`Namespace` key) to look up the object.
+
If the `Reconcile()` function returns an error, the controller will requeue and
retry the `Request`. If no error is returned, then depending on the
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result[Result],
the controller will either not retry the `Request`, immediately retry, or retry
after a specified duration.
.. Copy the code from the old project's `Handle()` function to the existing code
in your controller's `Reconcile()` function. Be sure to keep the initial section
in the `Reconcile()` code that looks up the object for the `Request` and checks
to see if it is deleted.
+
[source,golang]
----
import (
apierrors "k8s.io/apimachinery/pkg/api/errors"
cachev1alpha1 "github.com/example-inc/memcached-operator/pkg/apis/cache/v1alpha1"
...
)
func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) {
// Fetch the Memcached instance
instance := &cachev1alpha1.Memcached{}
err := r.client.Get(context.TODO()
request.NamespacedName, instance)
if err != nil {
if apierrors.IsNotFound(err) {
// Request object not found, could have been deleted after reconcile request.
// Owned objects are automatically garbage collected.
// Return and don't requeue
return reconcile.Result{}, nil
}
// Error reading the object - requeue the request.
return reconcile.Result{}, err
}
// Rest of your reconcile code goes here.
...
}
----
.. Change the return values in your reconcile code:
... Replace `return err` with `return reconcile.Result{}, err`.
... Replace `return nil` with `return reconcile.Result{}, nil`.
.. To periodically reconcile a CR in your controller, you can set the
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result[RequeueAfter]
field for `reconcile.Result`. This will cause the controller to requeue the
`Request` and trigger the reconcile after the desired duration. Note that the
default value of `0` means no requeue.
+
[source,golang]
----
reconcilePeriod := 30 * time.Second
reconcileResult := reconcile.Result{RequeueAfter: reconcilePeriod}
...
// Update the status
err := r.client.Update(context.TODO(), memcached)
if err != nil {
log.Printf("failed to update memcached status: %v", err)
return reconcileResult, err
}
return reconcileResult, nil
----
.. Replace the calls to the SDK client (Create, Update, Delete, Get, List) with the
reconciler's client.
+
See the examples below and the `controller-runtime`
link:https://sdk.operatorframework.io/docs/building-operators/golang/references/client/[client API documentation]
in the `operator-sdk` project for more details:
+
[source,golang]
----
// Create
dep := &appsv1.Deployment{...}
err := sdk.Create(dep)
// v0.0.1
err := r.client.Create(context.TODO(), dep)
// Update
err := sdk.Update(dep)
// v0.0.1
err := r.client.Update(context.TODO(), dep)
// Delete
err := sdk.Delete(dep)
// v0.0.1
err := r.client.Delete(context.TODO(), dep)
// List
podList := &corev1.PodList{}
labelSelector := labels.SelectorFromSet(labelsForMemcached(memcached.Name))
listOps := &metav1.ListOptions{LabelSelector: labelSelector}
err := sdk.List(memcached.Namespace, podList, sdk.WithListOptions(listOps))
// v0.1.0
listOps := &client.ListOptions{Namespace: memcached.Namespace, LabelSelector: labelSelector}
err := r.client.List(context.TODO(), listOps, podList)
// Get
dep := &appsv1.Deployment{APIVersion: "apps/v1", Kind: "Deployment", Name: name, Namespace: namespace}
err := sdk.Get(dep)
// v0.1.0
dep := &appsv1.Deployment{}
err = r.client.Get(context.TODO(), types.NamespacedName{Name: name, Namespace: namespace}, dep)
----
.. Copy and initialize any other fields from your `Handler` struct into the `Reconcile<Kind>` struct:
+
[source,golang]
----
// newReconciler returns a new reconcile.Reconciler
func newReconciler(mgr manager.Manager) reconcile.Reconciler {
return &ReconcileMemcached{client: mgr.GetClient(), scheme: mgr.GetScheme(), foo: "bar"}
}
// ReconcileMemcached reconciles a Memcached object
type ReconcileMemcached struct {
client client.Client
scheme *runtime.Scheme
// Other fields
foo string
}
----
. *Copy changes from `main.go`.*
+
The main function for a v0.1.0 Operator in `cmd/manager/main.go` sets up the
link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager[Manager],
which registers the custom resources and starts all of the controllers.
+
There is no requirement to migrate the SDK functions `sdk.Watch()`,`sdk.Handle()`, and `sdk.Run()` from the old `main.go` since that logic is now defined in a
controller.
+
However, if there are any Operator-specific flags or settings defined in the old
`main.go` file, copy them over.
+
If you have any third party resource types registered with the SDK's scheme, see
link:https://sdk.operatorframework.io/docs/building-operators/golang/advanced-topics/#adding-3rd-party-resources-to-your-operator[Advanced Topics]
in the `operator-sdk` project for how to register them with the Manager's
scheme in the new project.
. *Copy user-defined files.*
+
If there are any user-defined `pkgs`, scripts, or documentation in the older
project, copy those files into the new project.
. *Copy changes to deployment manifests.*
+
For any updates made to the following manifests in the old project, copy the changes to their corresponding files in the new project. Be careful not to
directly overwrite the files, but inspect and make any changes necessary:
+
--
* `tmp/build/Dockerfile` to `build/Dockerfile`
** There is no tmp directory in the new project layout
* RBAC rules updates from `deploy/rbac.yaml` to `deploy/role.yaml` and
`deploy/role_binding.yaml`
* `deploy/cr.yaml` to `deploy/crds/<group>_<version>_<kind>_cr.yaml`
* `deploy/crd.yaml` to `deploy/crds/<group>_<version>_<kind>_crd.yaml`
--
. *Copy user-defined dependencies.*
+
For any user-defined dependencies added to the old project's `Gopkg.toml`, copy
and append them to the new project's `Gopkg.toml`. Run `dep ensure` to update
the vendor in the new project.
. *Confirm your changes.*
+
Build and run your Operator to verify that it works.

2
modules/olm-about-catalogs.adoc
View File

@@ -17,8 +17,6 @@ As a cluster administrator, you can create your own custom index image, either b
[IMPORTANT]
====
Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. As a result, Operators are unable to use removed APIs starting with the version of {product-title} that uses the Kubernetes version that removed the API.
If your cluster is using custom catalogs, see xref:../../operators/operator_sdk/osdk-working-bundle-images#osdk-control-compat_osdk-working-bundle-images[Controlling Operator compatibility with {product-title} versions] for more details about how Operator authors can update their projects to help avoid workload issues and prevent incompatible upgrades.
====
[NOTE]

63
modules/olm-enabling-operator-for-multi-arch.adoc
View File

@@ -1,63 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
:_mod-docs-content-type: PROCEDURE
[id="olm-enabling-operator-for-multi-arch_{context}"]
= Enabling your Operator for multiple architectures and operating systems
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 {product-title} 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:
[source,yaml]
----
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.
[NOTE]
====
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 `PackageManifest` API.
====
If a CSV does not include an `os` label, it is treated as if it has the following Linux support label by default:
[source,yaml]
----
labels:
operatorframework.io/os.linux: supported
----
If a CSV does not include an `arch` label, it is treated as if it has the following AMD64 support label by default:
[source,yaml]
----
labels:
operatorframework.io/arch.amd64: supported
----
If an Operator supports multiple node architectures or operating systems, you can add multiple labels, as well.
.Prerequisites
* 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.
.Procedure
* Add a label in the `metadata.labels` of your CSV for each supported architecture and operating system that your Operator supports:
+
[source,yaml]
----
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.

201
modules/olm-enabling-operator-restricted-network.adoc
View File

@@ -1,201 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
:_mod-docs-content-type: PROCEDURE
[id="olm-enabling-operator-for-restricted-network_{context}"]
= Enabling your Operator for restricted network environments
As an Operator author, your Operator must meet additional requirements to run properly in a restricted network, or disconnected, environment.
.Operator requirements for supporting disconnected mode
* 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.
// TODO: Include more info w/ better steps on how to do this:
//* You must understand the {product-title} proxy configuration.
.Prerequisites
* An Operator project with a CSV. The following procedure uses the Memcached Operator as an example for Go-, Ansible-, and Helm-based projects.
.Procedure
. Set an environment variable for the additional image references used by the Operator in the `config/manager/manager.yaml` file:
+
.Example `config/manager/manager.yaml` file
[%collapsible]
====
[source,yaml]
----
...
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:
+
.Example `controllers/memcached_controller.go` file
[%collapsible]
====
[source,diff]
----
// 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>`.
[NOTE]
=====
The `os.Getenv` function returns an empty string if a variable is not set. Set the `<related_image_environment_variable>` before changing the file.
=====
====
* For Ansible-based Operator projects, add the environment variable to the `roles/memcached/tasks/main.yml` file as shown in the following example:
+
.Example `roles/memcached/tasks/main.yml` file
[%collapsible]
====
[source,diff]
----
spec:
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:
+
.Example `watches.yaml` file
[%collapsible]
====
[source,yaml]
----
...
- 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:
+
.Example `helm-charts/memchached/values.yaml` file
[source,yaml]
----
...
relatedImage: ""
----
.. Edit the chart template in the `helm-charts/memcached/templates/deployment.yaml` file as shown in the following example:
+
.Example `helm-charts/memcached/templates/deployment.yaml` file
[%collapsible]
====
[source,yaml]
----
containers:
- 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:
+
.Example `Makefile`
[source,diff]
----
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` :
+
[source,terminal]
----
$ make bundle USE_IMAGE_DIGESTS=true
----
. Add the `disconnected` annotation, which indicates that the Operator works in a disconnected environment:
+
[source,yaml]
----
metadata:
annotations:
operators.openshift.io/infrastructure-features: '["disconnected"]'
----
+
Operators can be filtered in OperatorHub by this infrastructure feature.

3
modules/olm-operator-framework.adoc
View File

@@ -7,9 +7,6 @@
The Operator Framework is a family of tools and capabilities to deliver on the customer experience described above. It is not just about writing code; testing, delivering, and updating Operators is just as important. The Operator Framework components consist of open source tools to tackle these problems:
Operator SDK::
The Operator SDK assists Operator authors in bootstrapping, building, testing, and packaging their own Operator based on their expertise without requiring knowledge of Kubernetes API complexities.
Operator Lifecycle Manager::
Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. It is deployed by default in {product-title} {product-version}.

3
modules/olm-operator-maturity-model.adoc
View File

@@ -11,6 +11,3 @@ One can however generalize the scale of the maturity of the encapsulated operati
.Operator maturity model
image::operator-maturity-model.png[]
The above model also shows how these capabilities can best be developed through
the Helm, Go, and Ansible capabilities of the Operator SDK.

2
modules/olm-operatorhub-overview.adoc
View File

@@ -33,5 +33,3 @@ Cluster administrators can choose from catalogs grouped into the following categ
endif::[]
Operators on OperatorHub are packaged to run on OLM. This includes a YAML file called a cluster service version (CSV) containing all of the CRDs, RBAC rules, deployments, and container images required to install and securely run the Operator. It also contains user-visible information like a description of its features and supported Kubernetes versions.
The Operator SDK can be used to assist developers packaging their Operators for use on OLM and OperatorHub. If you have a commercial application that you want to make accessible to your customers, get it included using the certification workflow provided on the Red Hat Partner Connect portal at link:https://connect.redhat.com[connect.redhat.com].

21
modules/osdk-about-openapi-validation.adoc
View File

@@ -1,21 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-about-openapi-validation_{context}"]
= About OpenAPI validation
OpenAPIv3 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached custom resource (CR) when it is created or updated.
Markers, or annotations, are available to configure validations for your API. These markers always have a `+kubebuilder:validation` prefix.
[role="_additional-resources"]
.Additional resources
* For more details on the usage of markers in API code, see the following Kubebuilder documentation:
** link:https://book.kubebuilder.io/reference/generating-crd.html[CRD generation]
** link:https://book.kubebuilder.io/reference/markers.html[Markers]
** link:https://book.kubebuilder.io/reference/markers/crd-validation.html[List of OpenAPIv3 validation markers]
* For more details about OpenAPIv3 validation schemas in CRDs, see the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation].

62
modules/osdk-about-pkg-format-migration.adoc
View File

@@ -1,62 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-pkgman-to-bundle.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-about-pkg-format-migration_{context}"]
= About packaging format migration
The Operator SDK `pkgman-to-bundle` command helps in migrating Operator Lifecycle Manager (OLM) package manifests to bundles. The command takes an input package manifest directory and generates bundles for each of the versions of manifests present in the input directory. You can also then build bundle images for each of the generated bundles.
For example, consider the following `packagemanifests/` directory for a project in the package manifest format:
.Example package manifest format layout
[source,terminal]
----
packagemanifests/
└── etcd
├── 0.0.1
│ ├── etcdcluster.crd.yaml
│ └── etcdoperator.clusterserviceversion.yaml
├── 0.0.2
│ ├── etcdbackup.crd.yaml
│ ├── etcdcluster.crd.yaml
│ ├── etcdoperator.v0.0.2.clusterserviceversion.yaml
│ └── etcdrestore.crd.yaml
└── etcd.package.yaml
----
After running the migration, the following bundles are generated in the `bundle/` directory:
.Example bundle format layout
[source,terminal]
----
bundle/
├── bundle-0.0.1
│   ├── bundle.Dockerfile
│   ├── manifests
│   │   ├── etcdcluster.crd.yaml
│   │   ├── etcdoperator.clusterserviceversion.yaml
│   ├── metadata
│   │   └── annotations.yaml
│   └── tests
│   └── scorecard
│   └── config.yaml
└── bundle-0.0.2
├── bundle.Dockerfile
├── manifests
│   ├── etcdbackup.crd.yaml
│   ├── etcdcluster.crd.yaml
│   ├── etcdoperator.v0.0.2.clusterserviceversion.yaml
│   ├── etcdrestore.crd.yaml
├── metadata
│   └── annotations.yaml
└── tests
└── scorecard
└── config.yaml
----
Based on this generated layout, bundle images for both of the bundles are also built with the following names:
* `quay.io/example/etcd:0.0.1`
* `quay.io/example/etcd:0.0.2`

36
modules/osdk-ansible-cr-status-about.adoc
View File

@@ -1,36 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-ansible-cr-status-about_{context}"]
= About custom resource status in Ansible-based Operators
Ansible-based Operators automatically update custom resource (CR) link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource[`status` subresources] with generic information about the previous Ansible run. This includes the number of successful and failed tasks and relevant error messages as shown:
[source,yaml]
----
status:
conditions:
- ansibleResult:
changed: 3
completion: 2018-12-03T13:45:57.13329
failures: 1
ok: 6
skipped: 0
lastTransitionTime: 2018-12-03T13:45:57Z
message: 'Status code was -1 and not [200]: Request failed: <urlopen error [Errno
113] No route to host>'
reason: Failed
status: "True"
type: Failure
- lastTransitionTime: 2018-12-03T13:46:13Z
message: Running reconciliation
reason: Running
status: "True"
type: Running
----
Ansible-based Operators also allow Operator authors to supply custom status values with the `k8s_status` Ansible module, which is included in the link:https://galaxy.ansible.com/operator_sdk/util[`operator_sdk.util` collection]. This allows the author to update the `status` from within Ansible with any key-value pair as desired.
By default, Ansible-based Operators always include the generic Ansible run output as shown above. If you would prefer your application did _not_ update the status with Ansible output, you can track the status manually from your application.

57
modules/osdk-ansible-cr-status-manual.adoc
View File

@@ -1,57 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-cr-status-manual_{context}"]
= Tracking custom resource status manually
You can use the `operator_sdk.util` collection to modify your Ansible-based Operator to track custom resource (CR) status manually from your application.
.Prerequisites
* Ansible-based Operator project created by using the Operator SDK
.Procedure
. Update the `watches.yaml` file with a `manageStatus` field set to `false`:
+
[source,yaml]
----
- version: v1
group: api.example.com
kind: <kind>
role: <role>
manageStatus: false
----
. Use the `operator_sdk.util.k8s_status` Ansible module to update the subresource. For example, to update with key `test` and value `data`, `operator_sdk.util` can be used as shown:
+
[source,yaml]
----
- operator_sdk.util.k8s_status:
api_version: app.example.com/v1
kind: <kind>
name: "{{ ansible_operator_meta.name }}"
namespace: "{{ ansible_operator_meta.namespace }}"
status:
test: data
----
. You can declare collections in the `meta/main.yml` file for the role, which is included for scaffolded Ansible-based Operators:
+
[source,yaml]
----
collections:
- operator_sdk.util
----
. After declaring collections in the role meta, you can invoke the `k8s_status` module directly:
+
[source,yaml]
----
k8s_status:
...
status:
key1: value1
----

34
modules/osdk-ansible-create-api.adoc
View File

@@ -1,34 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-create-api-controller_{context}"]
= Creating an API
Use the Operator SDK CLI to create a Memcached API.
.Procedure
* Run the following command to create an API with group `cache`, version, `v1`, and kind `Memcached`:
+
[source,terminal]
----
$ operator-sdk create api \
--group cache \
--version v1 \
--kind Memcached \
--generate-role <1>
----
<1> Generates an Ansible role for the API.
After creating the API, your Operator project updates with the following structure:
Memcached CRD:: Includes a sample `Memcached` resource
Manager:: Program that reconciles the state of the cluster to the desired state by using:
+
--
* A reconciler, either an Ansible role or playbook
* A `watches.yaml` file, which connects the `Memcached` resource to the `memcached` Ansible role
--

58
modules/osdk-ansible-custom-resource-files.adoc
View File

@@ -1,58 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
[id="osdk-ansible-custom-resource-files_{context}"]
= Custom resource files
Operators use the Kubernetes extension mechanism, custom resource definitions (CRDs), so your custom resource (CR) looks and acts just like the built-in, native Kubernetes objects.
The CR file format is a Kubernetes resource file. The object has mandatory and optional fields:
.Custom resource fields
[cols="3,7",options="header"]
|===
|Field
|Description
|`apiVersion`
|Version of the CR to be created.
|`kind`
|Kind of the CR to be created.
|`metadata`
|Kubernetes-specific metadata to be created.
|`spec` (optional)
|Key-value list of variables which are passed to Ansible. This field is empty by default.
|`status`
|Summarizes the current state of the object. For Ansible-based Operators, the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource[`status` subresource] is enabled for CRDs and managed by the `operator_sdk.util.k8s_status` Ansible module by default, which includes `condition` information to the CR `status`.
|`annotations`
|Kubernetes-specific annotations to be appended to the CR.
|===
The following list of CR annotations modify the behavior of the Operator:
.Ansible-based Operator annotations
[cols="3,7",options="header"]
|===
|Annotation
|Description
|`ansible.operator-sdk/reconcile-period`
|Specifies the reconciliation interval for the CR. This value is parsed using the standard Golang package link:https://golang.org/pkg/time/[`time`]. Specifically, link:https://golang.org/pkg/time/#ParseDuration[`ParseDuration`] is used which applies the default suffix of `s`, giving the value in seconds.
|===
.Example Ansible-based Operator annotation
[source,yaml]
----
apiVersion: "test1.example.com/v1alpha1"
kind: "Test1"
metadata:
name: "example"
annotations:
ansible.operator-sdk/reconcile-period: "30s"
----

48
modules/osdk-ansible-extra-variables.adoc
View File

@@ -1,48 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
[id="osdk-ansible-extra-variables_{context}"]
= Extra variables sent to Ansible
Extra variables can be sent to Ansible, which are then managed by the Operator. The `spec` section of the custom resource (CR) passes along the key-value pairs as extra variables. This is equivalent to extra variables passed in to the `ansible-playbook` command.
The Operator also passes along additional variables under the `meta` field for the name of the CR and the namespace of the CR.
For the following CR example:
[source,yaml]
----
apiVersion: "app.example.com/v1alpha1"
kind: "Database"
metadata:
name: "example"
spec:
message: "Hello world 2"
newParameter: "newParam"
----
The structure passed to Ansible as extra variables is:
[source,json]
----
{ "meta": {
"name": "<cr_name>",
"namespace": "<cr_namespace>",
},
"message": "Hello world 2",
"new_parameter": "newParam",
"_app_example_com_database": {
<full_crd>
},
}
----
The `message` and `newParameter` fields are set in the top level as extra variables, and `meta` provides the relevant metadata for the CR as defined in the Operator. The `meta` fields can be accessed using dot notation in Ansible, for example:
[source,yaml]
----
---
- debug:
msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"
----

124
modules/osdk-ansible-inside-operator-local.adoc
View File

@@ -1,124 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-inside-operator-local_{context}"]
= Testing an Ansible-based Operator locally
You can test the logic inside of an Ansible-based Operator running locally by using the `make run` command from the top-level directory of your Operator project. The `make run` Makefile target runs the `ansible-operator` binary locally, which reads from the `watches.yaml` file and uses your `~/.kube/config` file to communicate with a Kubernetes cluster just as the `k8s` modules do.
[NOTE]
====
You can customize the roles path by setting the environment variable `ANSIBLE_ROLES_PATH` or by using the `ansible-roles-path` flag. If the role is not found in the `ANSIBLE_ROLES_PATH` value, the Operator looks for it in `{{current directory}}/roles`.
====
.Prerequisites
- link:https://ansible-runner.readthedocs.io/en/latest/install.html[Ansible Runner] v2.3.3+
- link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plugin] v1.0.0+
- Performed the previous steps for testing the Kubernetes Collection locally
.Procedure
. Install your custom resource definition (CRD) and proper role-based access control (RBAC) definitions for your custom resource (CR):
+
[source,terminal]
----
$ make install
----
+
.Example output
[source,terminal]
----
/usr/bin/kustomize build config/crd | kubectl apply -f -
customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created
----
. Run the `make run` command:
+
[source,terminal]
----
$ make run
----
+
.Example output
[source,terminal]
----
/home/user/memcached-operator/bin/ansible-operator run
{"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
...
{"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"}
{"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
{"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
{"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
{"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
{"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
{"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
{"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
{"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}
----
+
With the Operator now watching your CR for events, the creation of a CR will trigger your Ansible role to run.
+
[NOTE]
====
Consider an example `config/samples/<gvk>.yaml` CR manifest:
[source,yaml]
----
apiVersion: <group>.example.com/v1alpha1
kind: <kind>
metadata:
name: "<kind>-sample"
----
Because the `spec` field is not set, Ansible is invoked with no extra variables. Passing extra variables from a CR to Ansible is covered in another section. It is important to set reasonable defaults for the Operator.
====
. Create an instance of your CR with the default variable `state` set to `present`:
+
[source,terminal]
----
$ oc apply -f config/samples/<gvk>.yaml
----
. Check that the `example-config` config map was created:
+
[source,terminal]
----
$ oc get configmaps
----
+
.Example output
[source,terminal]
----
NAME STATUS AGE
example-config Active 3s
----
. Modify your `config/samples/<gvk>.yaml` file to set the `state` field to `absent`. For example:
+
[source,yaml]
----
apiVersion: cache.example.com/v1
kind: Memcached
metadata:
name: memcached-sample
spec:
state: absent
----
. Apply the changes:
+
[source,terminal]
----
$ oc apply -f config/samples/<gvk>.yaml
----
. Confirm that the config map is deleted:
+
[source,terminal]
----
$ oc get configmap
----

22
modules/osdk-ansible-inside-operator-logs-full-result.adoc
View File

@@ -1,22 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-inside-operator-logs-full-result_{context}"]
= Enabling full Ansible results in logs
You can set the environment variable `ANSIBLE_DEBUG_LOGS` to `True` to enable checking the full Ansible result in logs, which can be helpful when debugging.
.Procedure
* Edit the `config/manager/manager.yaml` and `config/default/manager_metrics_patch.yaml` files to include the following configuration:
+
[source,terminal]
----
containers:
- name: manager
env:
- name: ANSIBLE_DEBUG_LOGS
value: "True"
----

25
modules/osdk-ansible-inside-operator-logs-verbose.adoc
View File

@@ -1,25 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-inside-operator-logs-verbose_{context}"]
= Enabling verbose debugging in logs
While developing an Ansible-based Operator, it can be helpful to enable additional debugging in logs.
.Procedure
* Add the `ansible.sdk.operatorframework.io/verbosity` annotation to your custom resource to enable the verbosity level that you want. For example:
+
[source,terminal]
----
apiVersion: "cache.example.com/v1alpha1"
kind: "Memcached"
metadata:
name: "example-memcached"
annotations:
"ansible.sdk.operatorframework.io/verbosity": "4"
spec:
size: 4
----

43
modules/osdk-ansible-inside-operator-logs-view.adoc
View File

@@ -1,43 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-inside-operator-logs-view_{context}"]
= Viewing Ansible logs
.Prerequisites
* Ansible-based Operator running as a deployment on a cluster
.Procedure
* To view logs from an Ansible-based Operator, run the following command:
+
[source,terminal]
----
$ oc logs deployment/<project_name>-controller-manager \
-c manager \//<1>
-n <namespace> <2>
----
<1> View logs from the `manager` container.
<2> If you used the `make deploy` command to run the Operator as a deployment, use the `<project_name>-system` namespace.
+
.Example output
[source,terminal]
----
{"level":"info","ts":1612732105.0579333,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
{"level":"info","ts":1612732105.0587437,"logger":"cmd","msg":"WATCH_NAMESPACE environment variable not set. Watching all namespaces.","Namespace":""}
I0207 21:08:26.110949 7 request.go:645] Throttling request took 1.035521578s, request: GET:https://172.30.0.1:443/apis/flowcontrol.apiserver.k8s.io/v1alpha1?timeout=32s
{"level":"info","ts":1612732107.768025,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":"127.0.0.1:8080"}
{"level":"info","ts":1612732107.768796,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
{"level":"info","ts":1612732107.7688773,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
{"level":"info","ts":1612732107.7688901,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
{"level":"info","ts":1612732107.770032,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
I0207 21:08:27.770185 7 leaderelection.go:243] attempting to acquire leader lease memcached-operator-system/memcached-operator...
{"level":"info","ts":1612732107.770202,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
I0207 21:08:27.784854 7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator
{"level":"info","ts":1612732107.7850506,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
{"level":"info","ts":1612732107.8853772,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
{"level":"info","ts":1612732107.8854098,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}
----

8
modules/osdk-ansible-inside-operator-logs.adoc
View File

@@ -1,8 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
[id="osdk-ansible-inside-operator-logs_{context}"]
= Ansible logs
Ansible-based Operators provide logs about the Ansible run, which can be useful for debugging your Ansible tasks. The logs can also contain detailed information about the internals of the Operator and its interactions with Kubernetes.

43
modules/osdk-ansible-k8s-install.adoc
View File

@@ -1,43 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-installing-k8s-collection_{context}"]
= Installing the Kubernetes Collection for Ansible
You can install the Kubernetes Collection for Ansible on your local workstation.
.Procedure
. Install Ansible 2.15+:
+
[source,terminal]
----
$ sudo dnf install ansible
----
. Install the link:https://pypi.org/project/kubernetes/[Python Kubernetes client] package:
+
[source,terminal]
----
$ pip install kubernetes
----
. Install the Kubernetes Collection using one of the following methods:
* You can install the collection directly from Ansible Galaxy:
+
[source,terminal]
----
$ ansible-galaxy collection install community.kubernetes
----
* If you have already initialized your Operator, you might have a `requirements.yml` file at the top level of your project. This file specifies Ansible dependencies that must be installed for your Operator to function. By default, this file installs the `community.kubernetes` collection as well as the `operator_sdk.util` collection, which provides modules and plugins for Operator-specific functions.
+
To install the dependent modules from the `requirements.yml` file:
+
[source,terminal]
----
$ ansible-galaxy collection install -r requirements.yml
----

122
modules/osdk-ansible-k8s-local.adoc
View File

@@ -1,122 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-k8s-local_{context}"]
= Testing the Kubernetes Collection locally
Operator developers can run the Ansible code from their local machine as opposed to running and rebuilding the Operator each time.
.Prerequisites
* Initialize an Ansible-based Operator project and create an API that has a generated Ansible role by using the Operator SDK
* Install the Kubernetes Collection for Ansible
.Procedure
. In your Ansible-based Operator project directory, modify the `roles/<kind>/tasks/main.yml` file with the Ansible logic that you want. The `roles/<kind>/` directory is created when you use the `--generate-role` flag while creating an API. The `<kind>` replaceable matches the kind that you specified for the API.
+
The following example creates and deletes a config map based on the value of a variable named `state`:
+
[source,yaml]
----
---
- name: set ConfigMap example-config to {{ state }}
community.kubernetes.k8s:
api_version: v1
kind: ConfigMap
name: example-config
namespace: <operator_namespace> <1>
state: "{{ state }}"
ignore_errors: true <2>
----
<1> Specify the namespace where you want the config map created.
<2> Setting `ignore_errors: true` ensures that deleting a nonexistent config map does not fail.
. Modify the `roles/<kind>/defaults/main.yml` file to set `state` to `present` by default:
+
[source,yaml]
----
---
state: present
----
. Create an Ansible playbook by creating a `playbook.yml` file in the top-level of your project directory, and include your `<kind>` role:
+
[source,yaml]
----
---
- hosts: localhost
roles:
- <kind>
----
. Run the playbook:
+
[source,terminal]
----
$ ansible-playbook playbook.yml
----
+
.Example output
[source,terminal]
----
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
PLAY [localhost] ********************************************************************************
TASK [Gathering Facts] ********************************************************************************
ok: [localhost]
TASK [memcached : set ConfigMap example-config to present] ********************************************************************************
changed: [localhost]
PLAY RECAP ********************************************************************************
localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
----
. Verify that the config map was created:
+
[source,terminal]
----
$ oc get configmaps
----
+
.Example output
[source,terminal]
----
NAME DATA AGE
example-config 0 2m1s
----
. Rerun the playbook setting `state` to `absent`:
+
[source,terminal]
----
$ ansible-playbook playbook.yml --extra-vars state=absent
----
+
.Example output
[source,terminal]
----
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
PLAY [localhost] ********************************************************************************
TASK [Gathering Facts] ********************************************************************************
ok: [localhost]
TASK [memcached : set ConfigMap example-config to absent] ********************************************************************************
changed: [localhost]
PLAY RECAP ********************************************************************************
localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
----
. Verify that the config map was deleted:
+
[source,terminal]
----
$ oc get configmaps
----

240
modules/osdk-ansible-metrics.adoc
View File

@@ -1,240 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-monitoring-prometheus.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-metrics_{context}"]
= Exposing custom metrics for Ansible-based Operators
As an Operator author creating Ansible-based Operators, you can use the Operator SDK's `osdk_metrics` module to expose custom Operator and Operand metrics, emit events, and support logging.
.Prerequisites
* Ansible-based Operator generated using the Operator SDK
* Prometheus Operator, which is deployed by default on {product-title} clusters
.Procedure
. Generate an Ansible-based Operator. This example uses a `testmetrics.com` domain:
+
[source,terminal]
----
$ operator-sdk init \
--plugins=ansible \
--domain=testmetrics.com
----
. Create a `metrics` API. This example uses a `kind` named `Testmetrics`:
+
[source,terminal]
----
$ operator-sdk create api \
--group metrics \
--version v1 \
--kind Testmetrics \
--generate-role
----
. Edit the `roles/testmetrics/tasks/main.yml` file and use the `osdk_metrics` module to create custom metrics for your Operator project:
+
.Example `roles/testmetrics/tasks/main.yml` file
[%collapsible]
====
[source,yaml]
----
---
# tasks file for Memcached
- name: start k8sstatus
k8s:
definition:
kind: Deployment
apiVersion: apps/v1
metadata:
name: '{{ ansible_operator_meta.name }}-memcached'
namespace: '{{ ansible_operator_meta.namespace }}'
spec:
replicas: "{{size}}"
selector:
matchLabels:
app: memcached
template:
metadata:
labels:
app: memcached
spec:
containers:
- name: memcached
command:
- memcached
- -m=64
- -o
- modern
- -v
image: "docker.io/memcached:1.4.36-alpine"
ports:
- containerPort: 11211
- osdk_metric:
name: my_thing_counter
description: This metric counts things
counter: {}
- osdk_metric:
name: my_counter_metric
description: Add 3.14 to the counter
counter:
increment: yes
- osdk_metric:
name: my_gauge_metric
description: Create my gauge and set it to 2.
gauge:
set: 2
- osdk_metric:
name: my_histogram_metric
description: Observe my histogram
histogram:
observe: 2
- osdk_metric:
name: my_summary_metric
description: Observe my summary
summary:
observe: 2
----
====
.Verification
. Run your Operator on a cluster. For example, to use the "run as a deployment" method:
.. Build the Operator image and push it to a registry:
+
[source,terminal]
----
$ make docker-build docker-push IMG=<registry>/<user>/<image_name>:<tag>
----
.. Install the Operator on a cluster:
+
[source,terminal]
----
$ make install
----
.. Deploy the Operator:
+
[source,terminal]
----
$ make deploy IMG=<registry>/<user>/<image_name>:<tag>
----
. Create a `Testmetrics` custom resource (CR):
.. Define the CR spec:
+
.Example `config/samples/metrics_v1_testmetrics.yaml` file
[%collapsible]
====
[source,yaml]
----
apiVersion: metrics.testmetrics.com/v1
kind: Testmetrics
metadata:
name: testmetrics-sample
spec:
size: 1
----
====
.. Create the object:
+
[source,terminal]
----
$ oc create -f config/samples/metrics_v1_testmetrics.yaml
----
. Get the pod details:
+
[source,terminal]
----
$ oc get pods
----
+
.Example output
[source,terminal]
----
NAME READY STATUS RESTARTS AGE
ansiblemetrics-controller-manager-<id> 2/2 Running 0 149m
testmetrics-sample-memcached-<id> 1/1 Running 0 147m
----
. Get the endpoint details:
+
[source,terminal]
----
$ oc get ep
----
+
.Example output
[source,terminal]
----
NAME ENDPOINTS AGE
ansiblemetrics-controller-manager-metrics-service 10.129.2.70:8443 150m
----
. Request a custom metrics token:
+
[source,terminal]
----
$ token=`oc create token prometheus-k8s -n openshift-monitoring`
----
. Check the metrics values:
.. Check the `my_counter_metric` value:
+
[source,terminal]
----
$ oc exec ansiblemetrics-controller-manager-<id> -- curl -k -H "Authoriza
tion: Bearer $token" 'https://10.129.2.70:8443/metrics' | grep my_counter
----
+
.Example output
[source,terminal]
----
HELP my_counter_metric Add 3.14 to the counter
TYPE my_counter_metric counter
my_counter_metric 2
----
.. Check the `my_gauge_metric` value:
+
[source,terminal]
----
$ oc exec ansiblemetrics-controller-manager-<id> -- curl -k -H "Authoriza
tion: Bearer $token" 'https://10.129.2.70:8443/metrics' | grep gauge
----
+
.Example output
[source,terminal]
----
HELP my_gauge_metric Create my gauge and set it to 2.
----
.. Check the `my_histogram_metric` and `my_summary_metric` values:
+
[source,terminal]
----
$ oc exec ansiblemetrics-controller-manager-<id> -- curl -k -H "Authoriza
tion: Bearer $token" 'https://10.129.2.70:8443/metrics' | grep Observe
----
+
.Example output
[source,terminal]
----
HELP my_histogram_metric Observe my histogram
HELP my_summary_metric Observe my summary
----

85
modules/osdk-ansible-modify-manager.adoc
View File

@@ -1,85 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ansible-modify-manager_{context}"]
= Modifying the manager
Update your Operator project to provide the reconcile logic, in the form of an Ansible role, which runs every time a `Memcached` resource is created, updated, or deleted.
.Procedure
. Update the `roles/memcached/tasks/main.yml` file with the following structure:
+
[source,yaml]
----
---
- name: start memcached
k8s:
definition:
kind: Deployment
apiVersion: apps/v1
metadata:
name: '{{ ansible_operator_meta.name }}-memcached'
namespace: '{{ ansible_operator_meta.namespace }}'
spec:
replicas: "{{size}}"
selector:
matchLabels:
app: memcached
template:
metadata:
labels:
app: memcached
spec:
containers:
- name: memcached
command:
- memcached
- -m=64
- -o
- modern
- -v
image: "docker.io/memcached:1.4.36-alpine"
ports:
- containerPort: 11211
----
+
This `memcached` role ensures a `memcached` deployment exist and sets the deployment size.
. Set default values for variables used in your Ansible role by editing the `roles/memcached/defaults/main.yml` file:
+
[source,yaml]
----
---
# defaults file for Memcached
size: 1
----
. Update the `Memcached` sample resource in the `config/samples/cache_v1_memcached.yaml` file with the following structure:
+
[source,yaml]
----
apiVersion: cache.example.com/v1
kind: Memcached
metadata:
labels:
app.kubernetes.io/name: memcached
app.kubernetes.io/instance: memcached-sample
app.kubernetes.io/part-of: memcached-operator
app.kubernetes.io/managed-by: kustomize
app.kubernetes.io/created-by: memcached-operator
name: memcached-sample
spec:
size: 3
----
+
The key-value pairs in the custom resource (CR) spec are passed to Ansible as extra variables.
[NOTE]
====
The names of all variables in the `spec` field are converted to snake case, meaning lowercase with an underscore, by the Operator before running Ansible. For example, `serviceAccount` in the spec becomes `service_account` in Ansible.
You can disable this case conversion by setting the `snakeCaseParameters` option to `false` in your `watches.yaml` file. It is recommended that you perform some type validation in Ansible on the variables to ensure that your application is receiving expected input.
====

60
modules/osdk-ansible-project-layout.adoc
View File

@@ -1,60 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc
[id="osdk-ansible-project-layout_{context}"]
= Ansible-based project layout
Ansible-based Operator projects generated using the `operator-sdk init --plugins ansible` command contain the following directories and files:
[options="header",cols="1,4"]
|===
|File or directory |Purpose
|`Dockerfile`
|Dockerfile for building the container image for the Operator.
|`Makefile`
|Targets for building, publishing, deploying the container image that wraps the Operator binary, and targets for installing and uninstalling the custom resource definition (CRD).
|`PROJECT`
|YAML file containing metadata information for the Operator.
|`config/crd`
|Base CRD files and the `kustomization.yaml` file settings.
|`config/default`
|Collects all Operator manifests for deployment. Use by the `make deploy` command.
|`config/manager`
|Controller manager deployment.
|`config/prometheus`
|`ServiceMonitor` resource for monitoring the Operator.
|`config/rbac`
|Role and role binding for leader election and authentication proxy.
|`config/samples`
|Sample resources created for the CRDs.
|`config/testing`
|Sample configurations for testing.
|`playbooks/`
|A subdirectory for the playbooks to run.
|`roles/`
|Subdirectory for the roles tree to run.
|`watches.yaml`
|Group/version/kind (GVK) of the resources to watch, and the Ansible invocation method. New entries are added by using the `create api` command.
|`requirements.yml`
|YAML file containing the Ansible collections and role dependencies to install during a build.
|`molecule/`
|Molecule scenarios for end-to-end testing of your role and Operator.
|===

13
modules/osdk-ansible-runner-directory.adoc
View File

@@ -1,13 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
[id="osdk-ansible-runner-directory_{context}"]
= Ansible Runner directory
Ansible Runner keeps information about Ansible runs in the container. This is located at `/tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name>`.
[role="_additional-resources"]
.Additional resources
* To learn more about the `runner` directory, see the link:https://ansible-runner.readthedocs.io/en/latest/index.html[Ansible Runner documentation].

120
modules/osdk-ansible-watches-file.adoc
View File

@@ -1,120 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
[id="osdk-ansible-watches-file_{context}"]
= watches.yaml file
A _group/version/kind (GVK)_ is a unique identifier for a Kubernetes API. The `watches.yaml` file contains a list of mappings from custom resources (CRs), identified by its GVK, to an Ansible role or playbook. The Operator expects this mapping file in a predefined location at `/opt/ansible/watches.yaml`.
.`watches.yaml` file mappings
[cols="3,7",options="header"]
|===
|Field
|Description
|`group`
|Group of CR to watch.
|`version`
|Version of CR to watch.
|`kind`
|Kind of CR to watch
|`role` (default)
|Path to the Ansible role added to the container. For example, if your `roles` directory is at `/opt/ansible/roles/` and your role is named `busybox`, this value would be `/opt/ansible/roles/busybox`. This field is mutually exclusive with the `playbook` field.
|`playbook`
|Path to the Ansible playbook added to the container. This playbook is expected to be a way to call roles. This field is mutually exclusive with the `role` field.
|`reconcilePeriod` (optional)
|The reconciliation interval, how often the role or playbook is run, for a given CR.
|`manageStatus` (optional)
|When set to `true` (default), the Operator manages the status of the CR generically. When set to `false`, the status of the CR is managed elsewhere, by the specified role or playbook or in a separate controller.
|===
.Example `watches.yaml` file
[source,yaml]
----
- version: v1alpha1 <1>
group: test1.example.com
kind: Test1
role: /opt/ansible/roles/Test1
- version: v1alpha1 <2>
group: test2.example.com
kind: Test2
playbook: /opt/ansible/playbook.yml
- version: v1alpha1 <3>
group: test3.example.com
kind: Test3
playbook: /opt/ansible/test3.yml
reconcilePeriod: 0
manageStatus: false
----
<1> Simple example mapping `Test1` to the `test1` role.
<2> Simple example mapping `Test2` to a playbook.
<3> More complex example for the `Test3` kind. Disables re-queuing and managing the CR status in the playbook.
[id="osdk-ansible-watches-file-advanced_{context}"]
== Advanced options
Advanced features can be enabled by adding them to your `watches.yaml` file per GVK. They can go below the `group`, `version`, `kind` and `playbook` or `role` fields.
Some features can be overridden per resource using an annotation on that CR. The options that can be overridden have the annotation specified below.
.Advanced watches.yaml file options
[cols="3,2,4,2,1",options="header"]
|===
|Feature
|YAML key
|Description
|Annotation for override
|Default value
|Reconcile period
|`reconcilePeriod`
|Time between reconcile runs for a particular CR.
|`ansible.operator-sdk/reconcile-period`
|`1m`
|Manage status
|`manageStatus`
|Allows the Operator to manage the `conditions` section of each CR `status` section.
|
|`true`
|Watch dependent resources
|`watchDependentResources`
|Allows the Operator to dynamically watch resources that are created by Ansible.
|
|`true`
|Watch cluster-scoped resources
|`watchClusterScopedResources`
|Allows the Operator to watch cluster-scoped resources that are created by Ansible.
|
|`false`
|Max runner artifacts
|`maxRunnerArtifacts`
|Manages the number of link:https://ansible-runner.readthedocs.io/en/latest/intro.html#runner-artifacts-directory-hierarchy[artifact directories] that Ansible Runner keeps in the Operator container for each individual resource.
|`ansible.operator-sdk/max-runner-artifacts`
|`20`
|===
.Example watches.yml file with advanced options
[source,yaml]
----
- version: v1alpha1
group: app.example.com
kind: AppService
playbook: /opt/ansible/playbook.yml
maxRunnerArtifacts: 30
reconcilePeriod: 5s
manageStatus: False
watchDependentResources: False
----

109
modules/osdk-apiservices.adoc
View File

@@ -1,109 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-apiservices_{context}"]
= Understanding your API services
As with CRDs, there are two types of API services that your Operator may use: _owned_ and _required_.
[id="osdk-apiservices-owned_{context}"]
== Owned API services
When a CSV owns an API service, it is responsible for describing the deployment of the extension `api-server` that backs it and the group/version/kind (GVK) it provides.
An API service is uniquely identified by the group/version it provides and can be listed multiple times to denote the different kinds it is expected to provide.
.Owned API service fields
[cols="2a,5a,2",options="header"]
|===
|Field |Description |Required/optional
|`Group`
|Group that the API service provides, for example `database.example.com`.
|Required
|`Version`
|Version of the API service, for example `v1alpha1`.
|Required
|`Kind`
|A kind that the API service is expected to provide.
|Required
|`Name`
|The plural name for the API service provided.
|Required
|`DeploymentName`
|Name of the deployment defined by your CSV that corresponds to your API service (required for owned API services). During the CSV pending phase, the OLM Operator searches the `InstallStrategy` of your CSV for a `Deployment` spec with a matching name, and if not found, does not transition the CSV to the "Install Ready" phase.
|Required
|`DisplayName`
|A human readable version of your API service name, for example `MongoDB Standalone`.
|Required
|`Description`
|A short description of how this API service is used by the Operator or a description of the functionality provided by the API service.
|Required
|`Resources`
a|Your API services own one or more types of Kubernetes objects. These are listed in the resources section to inform your users of the objects they might need to troubleshoot or how to connect to the application, such as the service or ingress rule that exposes a database.
It is recommended to only list out the objects that are important to a human, not an exhaustive list of everything you orchestrate. For example, do not list config maps that store internal state that are not meant to be modified by a user.
|Optional
|`SpecDescriptors`, `StatusDescriptors`, and `ActionDescriptors`
|Essentially the same as for owned CRDs.
|Optional
|===
[id="osdk-apiservices-resource-creation_{context}"]
=== API service resource creation
Operator Lifecycle Manager (OLM) is responsible for creating or replacing the service and API service resources for each unique owned API service:
* Service pod selectors are copied from the CSV deployment matching the `DeploymentName` field of the API service description.
* A new CA key/certificate pair is generated for each installation and the base64-encoded CA bundle is embedded in the respective API service resource.
[id="osdk-apiservices-service-certs_{context}"]
=== API service serving certificates
OLM handles generating a serving key/certificate pair whenever an owned API service is being installed. The serving certificate has a common name (CN) containing the hostname of the generated `Service` resource and is signed by the private key of the CA bundle embedded in the corresponding API service resource.
The certificate is stored as a type `kubernetes.io/tls` secret in the deployment namespace, and a volume named `apiservice-cert` is automatically appended to the volumes section of the deployment in the CSV matching the `DeploymentName` field of the API service description.
If one does not already exist, a volume mount with a matching name is also appended to all containers of that deployment. This allows users to define a volume mount with the expected name to accommodate any custom path requirements. The path of the generated volume mount defaults to `/apiserver.local.config/certificates` and any existing volume mounts with the same path are replaced.
[id="osdk-apiservice-required_{context}"]
== Required API services
OLM ensures all required CSVs have an API service that is available and all expected GVKs are discoverable before attempting installation. This allows a CSV to rely on specific kinds provided by API services it does not own.
.Required API service fields
[cols="2a,5a,2",options="header"]
|===
|Field |Description |Required/optional
|`Group`
|Group that the API service provides, for example `database.example.com`.
|Required
|`Version`
|Version of the API service, for example `v1alpha1`.
|Required
|`Kind`
|A kind that the API service is expected to provide.
|Required
|`DisplayName`
|A human readable version of your API service name, for example `MongoDB Standalone`.
|Required
|`Description`
|A short description of how this API service is used by the Operator or a description of the functionality provided by the API service.
|Required
|===

350
modules/osdk-building-helm-operator.adoc
View File

@@ -1,350 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-helm.adoc
[id="osdk-building-helm-operator_{context}"]
= Building a Helm-based Operator using the Operator SDK
This procedure walks through an example of building a simple Nginx Operator powered by a Helm chart using tools and libraries provided by the Operator SDK.
[TIP]
====
It is best practice to build a new Operator for each chart. This can allow for more native-behaving Kubernetes APIs (for example, `oc get Nginx`) and flexibility if you ever want to write a fully-fledged Operator in Go, migrating away from a Helm-based Operator.
====
.Prerequisites
- Operator SDK CLI installed on the development workstation
- Access to a Kubernetes-based cluster v1.11.3+ (for example {product-title} {product-version}) using an account with `cluster-admin` permissions
- OpenShift CLI (`oc`) v{product-version}+ installed
.Procedure
. *Create a new Operator project.* A namespace-scoped Operator watches and manages resources in a single namespace. Namespace-scoped Operators are preferred because of their flexibility. They enable decoupled upgrades, namespace isolation for failures and monitoring, and differing API definitions.
+
To create a new Helm-based, namespace-scoped `nginx-operator` project, use the following command:
+
[source,terminal]
----
$ operator-sdk new nginx-operator \
--api-version=example.com/v1alpha1 \
--kind=Nginx \
--type=helm
----
+
[source,terminal]
----
$ cd nginx-operator
----
+
This creates the `nginx-operator` project specifically for watching the Nginx resource with API version `example.com/v1apha1` and kind `Nginx`.
. *Customize the Operator logic.*
+
For this example, the `nginx-operator` executes the following reconciliation logic for each `Nginx` custom resource (CR):
+
--
* Create an Nginx deployment if it does not exist.
* Create an Nginx service if it does not exist.
* Create an Nginx ingress if it is enabled and does not exist.
* Ensure that the deployment, service, and optional ingress match the desired configuration (for example, replica count, image, service type) as specified by the Nginx CR.
--
+
By default, the `nginx-operator` watches `Nginx` resource events as shown in the `watches.yaml` file and executes Helm releases using the specified chart:
+
[source,yaml]
----
- version: v1alpha1
group: example.com
kind: Nginx
chart: /opt/helm/helm-charts/nginx
----
.. *Review the Nginx Helm chart.*
+
When a Helm Operator project is created, the Operator SDK creates an example Helm chart that contains a set of templates for a simple Nginx release.
+
For this example, templates are available for deployment, service, and ingress resources, along with a `NOTES.txt` template, which Helm chart developers use to convey helpful information about a release.
+
If you are not already familiar with Helm Charts, review the link:https://docs.helm.sh/developing_charts/[Helm Chart developer documentation].
.. *Understand the Nginx CR spec.*
+
Helm uses a concept called link:https://docs.helm.sh/using_helm/#customizing-the-chart-before-installing[values] to provide customizations to the defaults of a Helm chart, which are defined in the `values.yaml` file.
+
Override these defaults by setting the desired values in the CR spec. You can use the number of replicas as an example:
... First, inspect the `helm-charts/nginx/values.yaml` file to find that the chart has a value called `replicaCount` and it is set to `1` by default. To have 2 Nginx instances in your deployment, your CR spec must contain `replicaCount: 2`.
+
Update the `deploy/crds/example.com_v1alpha1_nginx_cr.yaml` file to look like the following:
+
[source,yaml]
----
apiVersion: example.com/v1alpha1
kind: Nginx
metadata:
name: example-nginx
spec:
replicaCount: 2
----
... Similarly, the default service port is set to `80`. To instead use `8080`, update the `deploy/crds/example.com_v1alpha1_nginx_cr.yaml` file again by adding the service port override:
+
[source,yaml]
----
apiVersion: example.com/v1alpha1
kind: Nginx
metadata:
name: example-nginx
spec:
replicaCount: 2
service:
port: 8080
----
+
The Helm Operator applies the entire spec as if it was the contents of a values file, just like the `helm install -f ./overrides.yaml` command works.
. *Deploy the CRD.*
+
Before running the Operator, Kubernetes must know about the new custom resource definition (CRD) that the Operator will be watching. Deploy the following CRD:
+
[source,terminal]
----
$ oc create -f deploy/crds/example_v1alpha1_nginx_crd.yaml
----
. *Build and run the Operator.*
+
There are two ways to build and run the Operator:
+
--
* As a pod inside a Kubernetes cluster.
* As a Go program outside the cluster using the `operator-sdk up` command.
--
+
Choose one of the following methods:
.. *Run as a pod* inside a Kubernetes cluster. This is the preferred
method for production use.
... Build the `nginx-operator` image and push it to a registry:
+
[source,terminal]
----
$ operator-sdk build quay.io/example/nginx-operator:v0.0.1
----
+
[source,terminal]
----
$ podman push quay.io/example/nginx-operator:v0.0.1
----
... Deployment manifests are generated in the `deploy/operator.yaml` file. The deployment image in this file needs to be modified from the placeholder `REPLACE_IMAGE` to the previous built image. To do this, run:
+
[source,terminal]
----
$ sed -i 's|REPLACE_IMAGE|quay.io/example/nginx-operator:v0.0.1|g' deploy/operator.yaml
----
... Deploy the `nginx-operator` manifests:
+
[source,terminal]
----
$ oc create -f deploy/service_account.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/role.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/role_binding.yaml
----
+
[source,terminal]
----
$ oc create -f deploy/operator.yaml
----
... Verify that the `nginx-operator` deployment is up and running:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
nginx-operator 1 1 1 1 1m
----
.. *Run outside the cluster.* This method is preferred during the development cycle to speed up deployment and testing.
+
It is important that the chart path referenced in the `watches.yaml` file exists on your machine. By default, the `watches.yaml` file is scaffolded to work with an Operator image built with the `operator-sdk build` command. When developing and testing your Operator with the `operator-sdk run --local` command, the SDK looks in your local file system for this path.
... Create a symlink at this location to point to the path of your Helm chart:
+
[source,terminal]
----
$ sudo mkdir -p /opt/helm/helm-charts
----
+
[source,terminal]
----
$ sudo ln -s $PWD/helm-charts/nginx /opt/helm/helm-charts/nginx
----
... To run the Operator locally with the default Kubernetes configuration file present at `$HOME/.kube/config`:
+
[source,terminal]
----
$ operator-sdk run --local
----
+
To run the Operator locally with a provided Kubernetes configuration file:
+
[source,terminal]
----
$ operator-sdk run --local --kubeconfig=<path_to_config>
----
. *Deploy the `Nginx` CR.*
+
Apply the `Nginx` CR that you modified earlier:
+
[source,terminal]
----
$ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
----
+
Ensure that the `nginx-operator` creates the deployment for the CR:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 2 2 2 2 1m
----
+
Check the pods to confirm two replicas were created:
+
[source,terminal]
----
$ oc get pods
----
+
.Example output
[source,terminal]
----
NAME READY STATUS RESTARTS AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-fjcr9 1/1 Running 0 1m
example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-ljbzl 1/1 Running 0 1m
----
+
Check that the service port is set to `8080`:
+
[source,terminal]
----
$ oc get service
----
+
.Example output
[source,terminal]
----
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 8080/TCP 1m
----
. *Update the `replicaCount` and remove the port.*
+
Change the `spec.replicaCount` field from `2` to `3`, remove the `spec.service` field, and apply the change:
+
[source,terminal]
----
$ cat deploy/crds/example.com_v1alpha1_nginx_cr.yaml
----
+
.Example output
[source,yaml]
----
apiVersion: "example.com/v1alpha1"
kind: "Nginx"
metadata:
name: "example-nginx"
spec:
replicaCount: 3
----
+
[source,terminal]
----
$ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
----
+
Confirm that the Operator changes the deployment size:
+
[source,terminal]
----
$ oc get deployment
----
+
.Example output
[source,terminal]
----
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 3 3 3 3 1m
----
+
Check that the service port is set to the default `80`:
+
[source,terminal]
----
$ oc get service
----
+
.Example output
[source,terminal]
----
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 80/TCP 1m
----
. *Clean up the resources:*
+
[source,terminal]
----
$ oc delete -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/operator.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/role_binding.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/role.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/service_account.yaml
----
+
[source,terminal]
----
$ oc delete -f deploy/crds/example_v1alpha1_nginx_crd.yaml
----

92
modules/osdk-bundle-operator.adoc
View File

@@ -1,92 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
// * operators/operator_sdk/osdk-working-bundle-images.adoc
ifeval::["{context}" == "osdk-golang-tutorial"]
:golang:
endif::[]
ifeval::["{context}" == "osdk-working-bundle-images"]
:golang:
endif::[]
:_mod-docs-content-type: PROCEDURE
[id="osdk-bundle-operator_{context}"]
= Bundling an Operator
The Operator bundle format is the default packaging method for Operator SDK and Operator Lifecycle Manager (OLM). You can get your Operator ready for use on OLM by using the Operator SDK to build and push your Operator project as a bundle image.
.Prerequisites
- Operator SDK CLI installed on a development workstation
- OpenShift CLI (`oc`) v{product-version}+ installed
- Operator project initialized by using the Operator SDK
ifdef::golang[]
- If your Operator is Go-based, your project must be updated to use supported images for running on {product-title}
endif::[]
.Procedure
. Run the following `make` commands in your Operator project directory to build and push your Operator image. Modify the `IMG` argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io.
.. Build the image:
+
[source,terminal]
----
$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>
----
+
[NOTE]
====
The Dockerfile generated by the SDK for the Operator explicitly references `GOARCH=amd64` for `go build`. This can be amended to `GOARCH=$TARGETARCH` for non-AMD64 architectures. Docker will automatically set the environment variable to the value specified by `–platform`. With Buildah, the `–build-arg` will need to be used for the purpose. For more information, see link:https://sdk.operatorframework.io/docs/advanced-topics/multi-arch/#supporting-multiple-architectures[Multiple Architectures].
====
.. Push the image to a repository:
+
[source,terminal]
----
$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>
----
. Create your Operator bundle manifest by running the `make bundle` command, which invokes several commands, including the Operator SDK `generate bundle` and `bundle validate` subcommands:
+
[source,terminal]
----
$ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>
----
+
Bundle manifests for an Operator describe how to display, create, and manage an application. 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` object
* A bundle metadata directory named `bundle/metadata`
* All custom resource definitions (CRDs) in a `config/crd` directory
* A Dockerfile `bundle.Dockerfile`
--
+
These files are then automatically validated by using `operator-sdk bundle validate` to ensure the on-disk bundle representation is correct.
. Build and push your bundle image by running the following commands. OLM consumes Operator bundles using an index image, which reference one or more bundle images.
.. Build the bundle image. Set `BUNDLE_IMG` with the details for the registry, user namespace, and image tag where you intend to push the image:
+
[source,terminal]
----
$ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
----
.. Push the bundle image:
+
[source,terminal]
----
$ docker push <registry>/<user>/<bundle_image_name>:<tag>
----
ifeval::["{context}" == "osdk-golang-tutorial"]
:!golang:
endif::[]
ifeval::["{context}" == "osdk-working-bundle-images"]
:!golang:
endif::[]

82
modules/osdk-bundle-upgrade-olm.adoc
View File

@@ -1,82 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-working-bundle-images.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-bundle-upgrade-olm_{context}"]
= Testing an Operator upgrade on Operator Lifecycle Manager
You can quickly test upgrading your Operator by using Operator Lifecycle Manager (OLM) integration in the Operator SDK, without requiring you to manually manage index images and catalog sources.
The `run bundle-upgrade` subcommand automates triggering an installed Operator to upgrade to a later version by specifying a bundle image for the later version.
.Prerequisites
- Operator installed with OLM either by using the `run bundle` subcommand or with traditional OLM installation
- A bundle image that represents a later version of the installed Operator
.Procedure
. If your Operator has not already been installed with OLM, install the earlier version either by using the `run bundle` subcommand or with traditional OLM installation.
+
[NOTE]
====
If the earlier version of the bundle was installed traditionally using OLM, the newer bundle that you intend to upgrade to must not exist in the index image referenced by the catalog source. Otherwise, running the `run bundle-upgrade` subcommand will cause the registry pod to fail because the newer bundle is already referenced by the index that provides the package and cluster service version (CSV).
====
+
For example, you can use the following `run bundle` subcommand for a Memcached Operator by specifying the earlier bundle image:
+
[source,terminal]
----
$ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1
----
+
.Example output
[source,terminal]
----
INFO[0006] Creating a File-Based Catalog of the bundle "quay.io/demo/memcached-operator:v0.0.1"
INFO[0008] Generated a valid File-Based Catalog
INFO[0012] Created registry pod: quay-io-demo-memcached-operator-v1-0-1
INFO[0012] Created CatalogSource: memcached-operator-catalog
INFO[0012] OperatorGroup "operator-sdk-og" created
INFO[0012] Created Subscription: memcached-operator-v0-0-1-sub
INFO[0015] Approved InstallPlan install-h9666 for the Subscription: memcached-operator-v0-0-1-sub
INFO[0015] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase
INFO[0015] Waiting for ClusterServiceVersion ""my-project/memcached-operator.v0.0.1" to appear
INFO[0026] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Pending
INFO[0028] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Installing
INFO[0059] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
INFO[0059] OLM has successfully installed "memcached-operator.v0.0.1"
----
. Upgrade the installed Operator by specifying the bundle image for the later Operator version:
+
[source,terminal]
----
$ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2
----
+
.Example output
[source,terminal]
----
INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project
INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project
INFO[0008] Generated a valid Upgraded File-Based Catalog
INFO[0009] Created registry pod: quay-io-demo-memcached-operator-v0-0-2
INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations
INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1"
INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub
INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase
INFO[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Pending
INFO[0042] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady
INFO[0043] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing
INFO[0044] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded
INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2"
----
. Clean up the installed Operators:
+
[source,terminal]
----
$ operator-sdk cleanup memcached-operator
----

65
modules/osdk-bundle-validate-about.adoc
View File

@@ -1,65 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-bundle-validate.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-about-bundle-validate_{context}"]
= About the bundle validate command
While the Operator SDK `scorecard` command can run tests on your Operator based on a configuration file and test images, the `bundle validate` subcommand can validate local bundle directories and remote bundle images for content and structure.
.`bundle validate` command syntax
[source,terminal]
----
$ operator-sdk bundle validate <bundle_dir_or_image> <flags>
----
[NOTE]
====
The `bundle validate` command runs automatically when you build your bundle using the `make bundle` command.
====
Bundle images are pulled from a remote registry and built locally before they are validated. Local bundle directories must contain Operator metadata and manifests. The bundle metadata and manifests must have a structure similar to the following bundle layout:
.Example bundle layout
[source,terminal]
----
./bundle
├── manifests
│   ├── cache.my.domain_memcacheds.yaml
│   └── memcached-operator.clusterserviceversion.yaml
└── metadata
└── annotations.yaml
----
Bundle tests pass validation and finish with an exit code of `0` if no errors are detected.
.Example output
[source,terminal]
----
INFO[0000] All validation tests have completed successfully
----
Tests fail validation and finish with an exit code of `1` if errors are detected.
.Example output
[source,terminal]
----
ERRO[0000] Error: Value cache.example.com/v1alpha1, Kind=Memcached: CRD "cache.example.com/v1alpha1, Kind=Memcached" is present in bundle "" but not defined in CSV
----
Bundle tests that result in warnings can still pass validation with an exit code of `0` as long as no errors are detected. Tests only fail on errors.
.Example output
[source,terminal]
----
WARN[0000] Warning: Value : (memcached-operator.v0.0.1) annotations not found
INFO[0000] All validation tests have completed successfully
----
For further information about the `bundle validate` subcommand, run:
[source,terminal]
----
$ operator-sdk bundle validate -h
----

62
modules/osdk-bundle-validate-run.adoc
View File

@@ -1,62 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-bundle-validate.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-bundle-validate-run_{context}"]
= Running the bundle validate command
The default validator runs a test every time you enter the `bundle validate` command. You can run optional validators using the `--select-optional` flag. Optional validators run tests in addition to the default test.
.Prerequisites
* Operator project generated by using the Operator SDK
.Procedure
. If you want to run the default validator against a local bundle directory, enter the following command from your Operator project directory:
+
[source,terminal]
----
$ operator-sdk bundle validate ./bundle
----
. If you want to run the default validator against a remote Operator bundle image, enter the following command:
+
[source,terminal]
----
$ operator-sdk bundle validate \
<bundle_registry>/<bundle_image_name>:<tag>
----
+
where:
<bundle_registry>:: Specifies the registry where the bundle is hosted, such as `quay.io/example`.
<bundle_image_name>:: Specifies the name of the bundle image, such as `memcached-operator`.
<tag>:: Specifies the tag of the bundle image, such as `v{osdk_ver}`.
+
[NOTE]
====
If you want to validate an Operator bundle image, you must host your image in a remote registry. The Operator SDK pulls the image and builds it locally before running tests. The `bundle validate` command does not support testing local bundle images.
====
. If you want to run an additional validator against an Operator bundle, enter the following command:
+
[source,terminal]
----
$ operator-sdk bundle validate \
<bundle_dir_or_image> \
--select-optional <test_label>
----
+
where:
<bundle_dir_or_image>:: Specifies the local bundle directory or remote bundle image, such as `~/projects/memcached` or `quay.io/example/memcached-operator:v{osdk_ver}`.
<test_label>:: Specifies the name of the validator you want to run, such as `name=good-practices`.
+
.Example output
[source,terminal]
----
ERRO[0000] Error: Value apiextensions.k8s.io/v1, Kind=CustomResource: unsupported media type registry+v1 for bundle object
WARN[0000] Warning: Value k8sevent.v0.0.1: owned CRD "k8sevents.k8s.k8sevent.com" has an empty description
----

37
modules/osdk-bundle-validate-tests.adoc
View File

@@ -1,37 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-bundle-validate.adoc
:_mod-docs-content-type: REFERENCE
[id="osdk-bundle-validate-tests_{context}"]
= Built-in bundle validate tests
The Operator SDK ships with pre-defined validators arranged into suites. If you run the `bundle validate` command without specifying a validator, the default test runs. The default test verifies that a bundle adheres to the specifications defined by the Operator Framework community. For more information, see "Bundle format".
You can run optional validators to test for issues such as OperatorHub compatibility or deprecated Kubernetes APIs. Optional validators always run in addition to the default test.
.`bundle validate` command syntax for optional test suites
[source,terminal]
----
$ operator-sdk bundle validate <bundle_dir_or_image>
--select-optional <test_label>
----
[id="osdk-bundle-validate-additional-tests_{context}"]
.Addtional `bundle validate` validators
[cols="3,7,3",options="header"]
|===
|Name |Description |Label
|Operator Framework
|This validator tests an Operator bundle against the entire suite of validators provided by the Operator Framework.
|`suite=operatorframework`
|OperatorHub
|This validator tests an Operator bundle for compatibility with OperatorHub.
|`name=operatorhub`
|Good Practices
|This validator tests whether an Operator bundle complies with good practices as defined by the Operator Framework. It checks for issues, such as an empty CRD description or unsupported Operator Lifecycle Manager (OLM) resources.
|`name=good-practices`
|===

33
modules/osdk-cli-ref-bundle.adoc
View File

@@ -1,33 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-bundle_{context}"]
= bundle
The `operator-sdk bundle` command manages Operator bundle metadata.
[id="osdk-cli-ref-bundle-validate_{context}"]
== validate
The `bundle validate` subcommand validates an Operator bundle.
.`bundle validate` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`-h`, `--help`
|Help output for the `bundle validate` subcommand.
|`--index-builder` (string)
|Tool to pull and unpack bundle images. Only used when validating a bundle image. Available options are `docker`, which is the default, `podman`, or `none`.
|`--list-optional`
|List all optional validators available. When set, no validators are run.
|`--select-optional` (string)
|Label selector to select optional validators to run. When run with the `--list-optional` flag, lists available optional validators.
|===

29
modules/osdk-cli-ref-cleanup.adoc
View File

@@ -1,29 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
:_mod-docs-content-type: REFERENCE
[id="osdk-cli-ref-cleanup_{context}"]
= cleanup
The `operator-sdk cleanup` command destroys and removes resources that were created for an Operator that was deployed with the `run` command.
.`cleanup` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`-h`, `--help`
|Help output for the `run bundle` subcommand.
|`--kubeconfig` (string)
|Path to the `kubeconfig` file to use for CLI requests.
|`-n`, `--namespace` (string)
|If present, namespace in which to run the CLI request.
|`--timeout <duration>`
|Time to wait for the command to complete before failing. The default value is `2m0s`.
|===

45
modules/osdk-cli-ref-completion.adoc
View File

@@ -1,45 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-completion_{context}"]
= completion
The `operator-sdk completion` command generates shell completions to make issuing CLI commands quicker and easier.
.`completion` subcommands
[options="header",cols="1,3"]
|===
|Subcommand |Description
|`bash`
|Generate bash completions.
|`zsh`
|Generate zsh completions.
|===
.`completion` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`-h, --help`
|Usage help output.
|===
For example:
[source,terminal]
----
$ operator-sdk completion bash
----
.Example output
[source,terminal]
----
# bash completion for operator-sdk -*- shell-script -*-
...
# ex: ts=4 sw=4 et filetype=sh
----

24
modules/osdk-cli-ref-create.adoc
View File

@@ -1,24 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-create_{context}"]
= create
The `operator-sdk create` command is used to create, or _scaffold_, a Kubernetes API.
[id="osdk-cli-ref-create-api_{context}"]
== api
The `create api` subcommand scaffolds a Kubernetes API. The subcommand must be run in a project that was initialized with the `init` command.
.`create api` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`-h`, `--help`
|Help output for the `run bundle` subcommand.
|===

66
modules/osdk-cli-ref-generate-bundle.adoc
View File

@@ -1,66 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-generate-bundle_{context}"]
= bundle
The `generate bundle` subcommand generates a set of bundle manifests, metadata, and a `bundle.Dockerfile` file for your Operator project.
[NOTE]
====
Typically, you run the `generate kustomize manifests` subcommand first to generate the input link:https://kustomize.io/[Kustomize] bases that are used by the `generate bundle` subcommand. However, you can use the `make bundle` command in an initialized project to automate running these commands in sequence.
====
.`generate bundle` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`--channels` (string)
|Comma-separated list of channels to which the bundle belongs. The default value is `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. This directory is different from the directory passed to the `--input-dir` flag.
|`-h`, `--help`
|Help for `generate bundle`
|`--input-dir` (string)
|Directory from which to read an existing bundle. This directory is the parent of your bundle `manifests` directory and is different from the `--deploy-dir` directory.
|`--kustomize-dir` (string)
|Directory containing Kustomize bases and a `kustomization.yaml` file for bundle manifests. The default path is `config/manifests`.
|`--manifests`
|Generate bundle manifests.
|`--metadata`
|Generate bundle metadata and Dockerfile.
|`--output-dir` (string)
|Directory to write the bundle to.
|`--overwrite`
|Overwrite the bundle metadata and Dockerfile if they exist. The default value is `true`.
|`--package` (string)
|Package name for the bundle.
|`-q`, `--quiet`
|Run in quiet mode.
|`--stdout`
|Write bundle manifest to standard out.
|`--version` (string)
|Semantic version of the Operator in the generated bundle. Set only when creating a new bundle or upgrading the Operator.
|===

42
modules/osdk-cli-ref-generate-kustomize.adoc
View File

@@ -1,42 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-generate-kustomize_{context}"]
= kustomize
The `generate kustomize` subcommand contains subcommands that generate link:https://kustomize.io/[Kustomize] data for the Operator.
[id="osdk-cli-ref-generate-kustomize-manifests_{context}"]
== manifests
The `generate kustomize manifests` subcommand generates or regenerates Kustomize bases and a `kustomization.yaml` file in the `config/manifests` directory, which are used to build bundle manifests by other Operator SDK commands. This command interactively asks for UI metadata, an important component of manifest bases, by default unless a base already exists or you set the `--interactive=false` flag.
.`generate kustomize manifests` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`--apis-dir` (string)
|Root directory for API type definitions.
|`-h`, `--help`
|Help for `generate kustomize manifests`.
|`--input-dir` (string)
|Directory containing existing Kustomize files.
|`--interactive`
|When set to `false`, if no Kustomize base exists, an interactive command prompt is presented to accept custom metadata.
|`--output-dir` (string)
|Directory where to write Kustomize files.
|`--package` (string)
|Package name.
|`-q`, `--quiet`
|Run in quiet mode.
|===

9
modules/osdk-cli-ref-generate.adoc
View File

@@ -1,9 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-generate_{context}"]
= generate
The `operator-sdk generate` command invokes a specific generator to generate code or manifests.

35
modules/osdk-cli-ref-init.adoc
View File

@@ -1,35 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-init_{context}"]
= init
The `operator-sdk init` command initializes an Operator project and generates, or _scaffolds_, a default project directory layout for the given plugin.
This command writes the following files:
* Boilerplate license file
* `PROJECT` file with the domain and repository
* `Makefile` to build the project
* `go.mod` file with project dependencies
* `kustomization.yaml` file for customizing manifests
* Patch file for customizing images for manager manifests
* Patch file for enabling Prometheus metrics
* `main.go` file to run
.`init` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`--help, -h`
|Help output for the `init` command.
|`--plugins` (string)
|Name and optionally version of the plugin to initialize the project with. Available plugins are `ansible.sdk.operatorframework.io/v1`, `go.kubebuilder.io/v2`, `go.kubebuilder.io/v3`, and `helm.sdk.operatorframework.io/v1`.
|`--project-version`
|Project version. Available values are `2` and `3-alpha`, which is the default.
|===

36
modules/osdk-cli-ref-run-bundle-upgrade.adoc
View File

@@ -1,36 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
:_mod-docs-content-type: REFERENCE
[id="osdk-cli-ref-run-bundle-upgrade_{context}"]
= bundle-upgrade
The `run bundle-upgrade` subcommand upgrades an Operator that was previously installed in the bundle format with Operator Lifecycle Manager (OLM).
.`run bundle-upgrade` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`--timeout <duration>`
|Upgrade timeout. The default value is `2m0s`.
|`--kubeconfig` (string)
|Path to the `kubeconfig` file to use for CLI requests.
|`-n`, `--namespace` (string)
|If present, namespace in which to run the CLI request.
|`--security-context-config <security_context>`
|Specifies the security context to use for the catalog pod. Allowed values include `restricted` and `legacy`. The default value is `legacy`. ^[1]^
|`-h`, `--help`
|Help output for the `run bundle` subcommand.
|===
[.small]
--
1. The `restricted` security context is not compatible with the `default` namespace. To configure your Operator's pod security admission in your production environment, see "Complying with pod security admission". For more information about pod security admission, see "Understanding and managing pod security admission".
--

42
modules/osdk-cli-ref-run-bundle.adoc
View File

@@ -1,42 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
:_mod-docs-content-type: REFERENCE
[id="osdk-cli-ref-run-bundle_{context}"]
= bundle
The `run bundle` subcommand deploys an Operator in the bundle format with Operator Lifecycle Manager (OLM).
.`run bundle` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`--index-image` (string)
|Index image in which to inject a bundle. The default image is `quay.io/operator-framework/upstream-opm-builder:latest`.
|`--install-mode <install_mode_value>`
|Install mode supported by the cluster service version (CSV) of the Operator, for example `AllNamespaces` or `SingleNamespace`.
|`--timeout <duration>`
|Install timeout. The default value is `2m0s`.
|`--kubeconfig` (string)
|Path to the `kubeconfig` file to use for CLI requests.
|`-n`, `--namespace` (string)
|If present, namespace in which to run the CLI request.
|`--security-context-config <security_context>`
|Specifies the security context to use for the catalog pod. Allowed values include `restricted` and `legacy`. The default value is `legacy`. ^[1]^
|`-h`, `--help`
|Help output for the `run bundle` subcommand.
|===
[.small]
--
1. The `restricted` security context is not compatible with the `default` namespace. To configure your Operator's pod security admission in your production environment, see "Complying with pod security admission". For more information about pod security admission, see "Understanding and managing pod security admission".
--

9
modules/osdk-cli-ref-run.adoc
View File

@@ -1,9 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-run_{context}"]
= run
The `operator-sdk run` command provides options that can launch the Operator in various environments.

53
modules/osdk-cli-ref-scorecard.adoc
View File

@@ -1,53 +0,0 @@
// Module included in the following assemblies:
//
// * cli_reference/osdk/cli-osdk-ref.adoc
// * operators/operator_sdk/osdk-cli-ref.adoc
[id="osdk-cli-ref-scorecard_{context}"]
= scorecard
The `operator-sdk scorecard` command runs the scorecard tool to validate an Operator bundle and provide suggestions for improvements. The command takes one argument, either a bundle image or directory containing manifests and metadata. If the argument holds an image tag, the image must be present remotely.
.`scorecard` flags
[options="header",cols="1,3"]
|===
|Flag |Description
|`-c`, `--config` (string)
|Path to scorecard configuration file. The default path is `bundle/tests/scorecard/config.yaml`.
|`-h`, `--help`
|Help output for the `scorecard` command.
|`--kubeconfig` (string)
|Path to `kubeconfig` file.
|`-L`, `--list`
|List which tests are available to run.
|`-n`, --namespace (string)
|Namespace in which to run the test images.
|`-o`, `--output` (string)
|Output format for results. Available values are `text`, which is the default, and `json`.
|`--pod-security <security_context>`
|Option to run scorecard with the specified security context. Allowed values include `restricted` and `legacy`. The default value is `legacy`. ^[1]^
|`-l`, `--selector` (string)
|Label selector to determine which tests are run.
|`-s`, `--service-account` (string)
|Service account to use for tests. The default value is `default`.
|`-x`, `--skip-cleanup`
|Disable resource cleanup after tests are run.
|`-w`, `--wait-time <duration>`
|Seconds to wait for tests to complete, for example `35s`. The default value is `30s`.
|===
[.small]
--
1. The `restricted` security context is not compatible with the `default` namespace. To configure your Operator's pod security admission in your production environment, see "Complying with pod security admission". For more information about pod security admission, see "Understanding and managing pod security admission".
--

58
modules/osdk-common-prereqs.adoc
View File

@@ -1,58 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-quickstart.adoc
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
// * operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
// * operators/operator_sdk/helm/osdk-helm-quickstart.adoc
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
// * operators/operator_sdk/osdk-working-bundle-images.adoc
ifeval::["{context}" == "osdk-ansible-quickstart"]
:ansible:
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:ansible:
endif::[]
ifeval::["{context}" == "osdk-golang-quickstart"]
:golang:
endif::[]
ifeval::["{context}" == "osdk-golang-tutorial"]
:golang:
endif::[]
[id="osdk-common-prereqs_{context}"]
= Prerequisites
* Operator SDK CLI installed
* OpenShift CLI (`oc`) {product-version}+ installed
ifdef::golang[]
* link:https://golang.org/dl/[Go] 1.21+
endif::[]
ifdef::ansible[]
* link:https://docs.ansible.com/ansible/latest/roadmap/ROADMAP_2_15.html[Ansible] 2.15.0
* link:https://ansible-runner.readthedocs.io/en/latest/install.html[Ansible Runner] 2.3.3+
* link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plugin] 1.0.0+
* link:https://www.python.org/downloads/[Python] 3.9+
* link:https://pypi.org/project/kubernetes/[Python Kubernetes client]
endif::[]
ifndef::openshift-dedicated,openshift-rosa[]
* Logged into an {product-title} {product-version} cluster with `oc` with an account that has `cluster-admin` permissions
endif::openshift-dedicated,openshift-rosa[]
ifdef::openshift-dedicated,openshift-rosa[]
* Logged into an {product-title} cluster with `oc` with an account that has `dedicated-admin` permissions
endif::openshift-dedicated,openshift-rosa[]
* To allow the cluster to pull the image, the repository where you push your image must be set as public, or you must configure an image pull secret
ifeval::["{context}" == "osdk-ansible-quickstart"]
:!ansible:
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:!ansible:
endif::[]
ifeval::["{context}" == "osdk-golang-quickstart"]
:!golang:
endif::[]
ifeval::["{context}" == "osdk-golang-tutorial"]
:!golang:
endif::[]

90
modules/osdk-control-compat.adoc
View File

@@ -1,90 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-working-bundle-images.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-control-compat_{context}"]
= Controlling Operator compatibility with {product-title} versions
[IMPORTANT]
====
Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. If your Operator is using a deprecated API, it might no longer work after the {product-title} cluster is upgraded to the Kubernetes version where the API has been removed.
As an Operator author, it is strongly recommended that you review the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/[Deprecated API Migration Guide] in Kubernetes documentation and keep your Operator projects up to date to avoid using deprecated and removed APIs. Ideally, you should update your Operator before the release of a future version of {product-title} that would make the Operator incompatible.
====
When an API is removed from an {product-title} version, Operators running on that cluster version that are still using removed APIs will no longer work properly. As an Operator author, you should plan to update your Operator projects to accommodate API deprecation and removal to avoid interruptions for users of your Operator.
[TIP]
====
You can check the event alerts of your Operators to find whether there are any warnings about APIs currently in use. The following alerts fire when they detect an API in use that will be removed in the next release:
`APIRemovedInNextReleaseInUse`::
APIs that will be removed in the next {product-title} release.
`APIRemovedInNextEUSReleaseInUse`::
APIs that will be removed in the next {product-title} link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[Extended Update Support (EUS)] release.
====
If a cluster administrator has installed your Operator, before they upgrade to the next version of {product-title}, they must ensure a version of your Operator is installed that is compatible with that next cluster version. While it is recommended that you update your Operator projects to no longer use deprecated or removed APIs, if you still need to publish your Operator bundles with removed APIs for continued use on earlier versions of {product-title}, ensure that the bundle is configured accordingly.
The following procedure helps prevent administrators from installing versions of your Operator on an incompatible version of {product-title}. These steps also prevent administrators from upgrading to a newer version of {product-title} that is incompatible with the version of your Operator that is currently installed on their cluster.
This procedure is also useful when you know that the current version of your Operator will not work well, for any reason, on a specific {product-title} version. By defining the cluster versions where the Operator should be distributed, you ensure that the Operator does not appear in a catalog of a cluster version which is outside of the allowed range.
[IMPORTANT]
====
Operators that use deprecated APIs can adversely impact critical workloads when cluster administrators upgrade to a future version of {product-title} where the API is no longer supported. If your Operator is using deprecated APIs, you should configure the following settings in your Operator project as soon as possible.
====
.Prerequisites
- An existing Operator project
.Procedure
. If you know that a specific bundle of your Operator is not supported and will not work correctly on {product-title} later than a certain cluster version, configure the maximum version of {product-title} that your Operator is compatible with. In your Operator project's cluster service version (CSV), set the `olm.maxOpenShiftVersion` annotation to prevent administrators from upgrading their cluster before upgrading the installed Operator to a compatible version:
+
[IMPORTANT]
====
You must use `olm.maxOpenShiftVersion` annotation only if your Operator bundle version cannot work in later versions. Be aware that cluster admins cannot upgrade their clusters with your solution installed. If you do not provide later version and a valid upgrade path, administrators may uninstall your Operator and can upgrade the cluster version.
====
+
.Example CSV with `olm.maxOpenShiftVersion` annotation
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
annotations:
"olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' <1>
----
<1> Specify the maximum cluster version of {product-title} that your Operator is compatible with. For example, setting `value` to `4.9` prevents cluster upgrades to {product-title} versions later than 4.9 when this bundle is installed on a cluster.
. If your bundle is intended for distribution in a Red Hat-provided Operator catalog, configure the compatible versions of {product-title} for your Operator by setting the following properties. This configuration ensures your Operator is only included in catalogs that target compatible versions of {product-title}:
+
[NOTE]
====
This step is only valid when publishing Operators in Red Hat-provided catalogs. If your bundle is only intended for distribution in a custom catalog, you can skip this step. For more details, see "Red Hat-provided Operator catalogs".
====
.. Set the `com.redhat.openshift.versions` annotation in your project's `bundle/metadata/annotations.yaml` file:
+
.Example `bundle/metadata/annotations.yaml` file with compatible versions
[source,yaml]
----
com.redhat.openshift.versions: "v4.7-v4.9" <1>
----
<1> Set to a range or single version.
.. To prevent your bundle from being carried on to an incompatible version of {product-title}, ensure that the index image is generated with the proper `com.redhat.openshift.versions` label in your Operator's bundle image. For example, if your project was generated using the Operator SDK, update the `bundle.Dockerfile` file:
+
.Example `bundle.Dockerfile` with compatible versions
+
[source,yaml]
----
LABEL com.redhat.openshift.versions="<versions>" <1>
----
<1> Set to a range or single version, for example, `v4.7-v4.9`. This setting defines the cluster versions where the Operator should be distributed, and the Operator does not appear in a catalog of a cluster version which is outside of the range.
You can now bundle a new version of your Operator and publish the updated version to a catalog for distribution.

20
modules/osdk-crd-templates.adoc
View File

@@ -1,20 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-crds-templates_{context}"]
= CRD templates
Users of your Operator must be made aware of which options are required versus optional. You can provide templates for each of your custom resource definitions (CRDs) with a minimum set of configuration as an annotation named `alm-examples`. Compatible UIs will pre-fill this template for users to further customize.
The annotation consists of a list of the kind, for example, the CRD name and the corresponding `metadata` and `spec` of the Kubernetes object.
The following full example provides templates for `EtcdCluster`, `EtcdBackup` and `EtcdRestore`:
[source,yaml]
----
metadata:
annotations:
alm-examples: >-
[{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdCluster","metadata":{"name":"example","namespace":"<operator_namespace>"},"spec":{"size":3,"version":"3.2.13"}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdRestore","metadata":{"name":"example-etcd-cluster"},"spec":{"etcdCluster":{"name":"example-etcd-cluster"},"backupStorageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdBackup","metadata":{"name":"example-etcd-cluster-backup"},"spec":{"etcdEndpoints":["<etcd-cluster-endpoints>"],"storageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}}]
----

9
modules/osdk-crds.adoc
View File

@@ -1,9 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-crds_{context}"]
= Understanding your custom resource definitions (CRDs)
There are two types of custom resource definitions (CRDs) that your Operator can use: ones that are _owned_ by it and ones that it depends on, which are _required_.

244
modules/osdk-create-cr.adoc
View File

@@ -1,244 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
ifeval::["{context}" == "osdk-golang-tutorial"]
:golang:
:app-proper: Memcached
:app: memcached
:group: cache
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:ansible:
:app-proper: Memcached
:app: memcached
:group: cache
endif::[]
ifeval::["{context}" == "osdk-helm-tutorial"]
:helm:
:app-proper: Nginx
:app: nginx
:group: demo
endif::[]
:_mod-docs-content-type: PROCEDURE
[id="osdk-create-cr_{context}"]
= Creating a custom resource
After your Operator is installed, you can test it by creating a custom resource (CR) that is now provided on the cluster by the Operator.
.Prerequisites
* Example {app-proper} Operator, which provides the `{app-proper}` CR, installed on a cluster
.Procedure
. Change to the namespace where your Operator is installed. For example, if you deployed the Operator using the `make deploy` command:
+
[source,terminal,subs="attributes+"]
----
$ oc project {app}-operator-system
----
. Edit the sample `{app-proper}` CR manifest at `config/samples/{group}_v1_{app}.yaml` to contain the following specification:
+
[source,yaml,subs="attributes+"]
----
apiVersion: {group}.example.com/v1
kind: {app-proper}
metadata:
name: {app}-sample
...
spec:
...
ifdef::helm[]
replicaCount: 3
endif::[]
ifndef::helm[]
size: 3
endif::[]
----
ifdef::helm[]
. The {app-proper} service account requires privileged access to run in {product-title}. Add the following security context constraint (SCC) to the service account for the `{app}-sample` pod:
+
[source,terminal,subs="attributes+"]
----
$ oc adm policy add-scc-to-user \
anyuid system:serviceaccount:{app}-operator-system:{app}-sample
----
endif::[]
. Create the CR:
+
[source,terminal,subs="attributes+"]
----
$ oc apply -f config/samples/{group}_v1_{app}.yaml
----
. Ensure that the `{app-proper}` Operator creates the deployment for the sample CR with the correct size:
+
[source,terminal]
----
$ oc get deployments
----
+
.Example output
[source,terminal]
ifdef::helm[]
----
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-operator-controller-manager 1/1 1 1 8m
nginx-sample 3/3 3 3 1m
----
endif::[]
ifndef::helm[]
----
NAME READY UP-TO-DATE AVAILABLE AGE
memcached-operator-controller-manager 1/1 1 1 8m
memcached-sample 3/3 3 3 1m
----
endif::[]
. Check the pods and CR status to confirm the status is updated with the {app-proper} pod names.
.. Check the pods:
+
[source,terminal]
----
$ oc get pods
----
+
.Example output
[source,terminal]
ifdef::helm[]
----
NAME READY STATUS RESTARTS AGE
nginx-sample-6fd7c98d8-7dqdr 1/1 Running 0 1m
nginx-sample-6fd7c98d8-g5k7v 1/1 Running 0 1m
nginx-sample-6fd7c98d8-m7vn7 1/1 Running 0 1m
----
endif::[]
ifndef::helm[]
----
NAME READY STATUS RESTARTS AGE
memcached-sample-6fd7c98d8-7dqdr 1/1 Running 0 1m
memcached-sample-6fd7c98d8-g5k7v 1/1 Running 0 1m
memcached-sample-6fd7c98d8-m7vn7 1/1 Running 0 1m
----
endif::[]
.. Check the CR status:
+
[source,terminal,subs="attributes+"]
----
$ oc get {app}/{app}-sample -o yaml
----
+
.Example output
[source,yaml,subs="attributes+"]
----
apiVersion: {group}.example.com/v1
kind: {app-proper}
metadata:
...
name: {app}-sample
...
spec:
ifdef::helm[]
replicaCount: 3
endif::[]
ifndef::helm[]
size: 3
endif::[]
status:
nodes:
- {app}-sample-6fd7c98d8-7dqdr
- {app}-sample-6fd7c98d8-g5k7v
- {app}-sample-6fd7c98d8-m7vn7
----
. Update the deployment size.
.. Update `config/samples/{group}_v1_{app}.yaml` file to change the `spec.size` field in the `{app-proper}` CR from `3` to `5`:
+
[source,terminal,subs="attributes+"]
----
$ oc patch {app} {app}-sample \
ifdef::helm[]
-p '{"spec":{"replicaCount": 5}}' \
endif::[]
ifndef::helm[]
-p '{"spec":{"size": 5}}' \
endif::[]
--type=merge
----
.. Confirm that the Operator changes the deployment size:
+
[source,terminal]
----
$ oc get deployments
----
+
.Example output
[source,terminal]
ifdef::helm[]
----
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-operator-controller-manager 1/1 1 1 10m
nginx-sample 5/5 5 5 3m
----
endif::[]
ifndef::helm[]
----
NAME READY UP-TO-DATE AVAILABLE AGE
memcached-operator-controller-manager 1/1 1 1 10m
memcached-sample 5/5 5 5 3m
----
endif::[]
. Delete the CR by running the following command:
+
[source,terminal,subs="attributes+"]
----
$ oc delete -f config/samples/{group}_v1_{app}.yaml
----
. Clean up the resources that have been created as part of this tutorial.
* If you used the `make deploy` command to test the Operator, run the following command:
+
[source,terminal]
----
$ make undeploy
----
* If you used the `operator-sdk run bundle` command to test the Operator, run the following command:
+
[source,terminal]
----
$ operator-sdk cleanup <project_name>
----
ifeval::["{context}" == "osdk-golang-tutorial"]
:!golang:
:!app-proper:
:!app:
:!group:
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:!ansible:
:!app-proper:
:!app:
:!group:
endif::[]
ifeval::["{context}" == "osdk-helm-tutorial"]
:!helm:
:!app-proper:
:!app:
:!group:
endif::[]

119
modules/osdk-create-project.adoc
View File

@@ -1,119 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
ifeval::["{context}" == "osdk-golang-tutorial"]
:golang:
:type: Go
:app: memcached
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:ansible:
:type: Ansible
:app: memcached
endif::[]
ifeval::["{context}" == "osdk-helm-tutorial"]
:helm:
:type: Helm
:app: nginx
endif::[]
:_mod-docs-content-type: PROCEDURE
[id="osdk-create-project_{context}"]
= Creating a project
Use the Operator SDK CLI to create a project called `{app}-operator`.
.Procedure
. Create a directory for the project:
+
[source,terminal,subs="attributes+"]
----
$ mkdir -p $HOME/projects/{app}-operator
----
. Change to the directory:
+
[source,terminal,subs="attributes+"]
----
$ cd $HOME/projects/{app}-operator
----
ifdef::golang[]
. Activate support for Go modules:
+
[source,terminal]
----
$ export GO111MODULE=on
----
endif::[]
. Run the `operator-sdk init` command
ifdef::ansible[]
with the `ansible` plugin
endif::[]
ifdef::helm[]
with the `helm` plugin
endif::[]
to initialize the project:
+
[source,terminal,subs="attributes+"]
ifdef::golang[]
----
$ operator-sdk init \
--domain=example.com \
--repo=github.com/example-inc/{app}-operator
----
+
[NOTE]
====
The `operator-sdk init` command uses the Go plugin by default.
====
+
The `operator-sdk init` command generates a `go.mod` file to be used with link:https://golang.org/ref/mod[Go modules]. The `--repo` flag is required when creating a project outside of `$GOPATH/src/`, because generated files require a valid module path.
endif::[]
ifdef::ansible[]
----
$ operator-sdk init \
--plugins=ansible \
--domain=example.com
----
endif::[]
ifdef::helm[]
----
$ operator-sdk init \
--plugins=helm \
--domain=example.com \
--group=demo \
--version=v1 \
--kind=Nginx
----
+
[NOTE]
====
By default, the `helm` plugin initializes a project using a boilerplate Helm chart. You can use additional flags, such as the `--helm-chart` flag, to initialize a project using an existing Helm chart.
====
+
The `init` command creates the `nginx-operator` project specifically for watching a resource with API version `example.com/v1` and kind `Nginx`.
. For Helm-based projects, the `init` command generates the RBAC rules in the `config/rbac/role.yaml` file based on the resources that would be deployed by the default manifest for the chart. Verify that the rules generated in this file meet the permission requirements of the Operator.
endif::[]
ifeval::["{context}" == "osdk-golang-tutorial"]
:!golang:
:!type:
:!app:
endif::[]
ifeval::["{context}" == "osdk-ansible-tutorial"]
:!ansible:
:!type:
:!app:
endif::[]
ifeval::["{context}" == "osdk-helm-tutorial"]
:!helm:
:!type:
:!app:
endif::[]

49
modules/osdk-csv-annotations-dep.adoc
View File

@@ -1,49 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-csv-manual-annotations-deprecated_{context}"]
= Deprecated infrastructure feature annotations
Starting in {product-title} 4.14, the `operators.openshift.io/infrastructure-features` group of annotations are deprecated by the group of annotations with the `features.operators.openshift.io` namespace. While you are encouraged to use the newer annotations, both groups are currently accepted when used in parallel.
These annotations detail the infrastructure features that an Operator supports. Users can view and filter by these features when discovering Operators through OperatorHub in the web console or on the link:https://catalog.redhat.com/software/search?deployed_as=Operator[Red Hat Ecosystem Catalog].
.Deprecated `operators.openshift.io/infrastructure-features` annotations
[cols="2a,4a",options="header"]
|===
|Valid annotation values |Description
|`disconnected`
|Operator supports being mirrored into disconnected catalogs, including all dependencies, and does not require internet access. All related images required for mirroring are listed by the Operator.
|`cnf`
|Operator provides a Cloud-native Network Functions (CNF) Kubernetes plugin.
|`cni`
|Operator provides a Container Network Interface (CNI) Kubernetes plugin.
|`csi`
|Operator provides a Container Storage Interface (CSI) Kubernetes plugin.
|`fips`
|Operator accepts the FIPS mode of the underlying platform and works on nodes that are booted into FIPS mode.
[IMPORTANT]
====
When running {op-system-base-full} or {op-system-first} booted in FIPS mode, {product-title} core components use the {op-system-base} cryptographic libraries that have been submitted to NIST for FIPS 140-2/140-3 Validation on only the x86_64, ppc64le, and s390x architectures.
====
|`proxy-aware`
|Operator supports running on a cluster behind a proxy. Operator accepts the standard proxy environment variables `HTTP_PROXY` and `HTTPS_PROXY`, which Operator Lifecycle Manager (OLM) provides to the Operator automatically when the cluster is configured to use a proxy. Required environment variables are passed down to Operands for managed workloads.
|===
.Example CSV with `disconnected` and `proxy-aware` support
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
annotations:
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
----

81
modules/osdk-csv-annotations-infra.adoc
View File

@@ -1,81 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
:_mod-docs-content-type: REFERENCE
[id="osdk-csv-annotations-infra_{context}"]
= Infrastructure features annotations
Annotations in the `features.operators.openshift.io` group detail the infrastructure features that an Operator might support, specified by setting a `"true"` or `"false"` value. Users can view and filter by these features when discovering Operators through OperatorHub in the web console or on the link:https://catalog.redhat.com/software/search?deployed_as=Operator[Red Hat Ecosystem Catalog]. These annotations are supported in {product-title} 4.10 and later.
[IMPORTANT]
====
The `features.operators.openshift.io` infrastructure feature annotations deprecate the `operators.openshift.io/infrastructure-features` annotations used in earlier versions of {product-title}. See "Deprecated infrastructure feature annotations" for more information.
====
.Infrastructure features annotations
[cols="4a,5a,3a,options="header"]
|===
|Annotation |Description |Valid values^[1]^
|`features.operators.openshift.io/disconnected`
|Specify whether an Operator supports being mirrored into disconnected catalogs, including all dependencies, and does not require internet access. The Operator leverages the `spec.relatedImages` CSV field to refer to any related image by its digest.
|`"true"` or `"false"`
|`features.operators.openshift.io/fips-compliant`
|Specify whether an Operator accepts the FIPS-140 configuration of the underlying platform and works on nodes that are booted into FIPS mode. In this mode, the Operator and any workloads it manages (operands) are solely calling the {op-system-base-full} cryptographic library submitted for FIPS-140 validation.
|`"true"` or `"false"`
|`features.operators.openshift.io/proxy-aware`
|Specify whether an Operator supports running on a cluster behind a proxy by accepting the standard `HTTP_PROXY` and `HTTPS_PROXY` proxy environment variables. If applicable, the Operator passes this information to the workload it manages (operands).
|`"true"` or `"false"`
|`features.operators.openshift.io/tls-profiles`
|Specify whether an Operator implements well-known tunables to modify the TLS cipher suite used by the Operator and, if applicable, any of the workloads it manages (operands).
|`"true"` or `"false"`
|`features.operators.openshift.io/token-auth-aws`
|Specify whether an Operator supports configuration for tokenized authentication with AWS APIs via AWS Secure Token Service (STS) by using the Cloud Credential Operator (CCO).
|`"true"` or `"false"`
|`features.operators.openshift.io/token-auth-azure`
|Specify whether an Operator supports configuration for tokenized authentication with Azure APIs via Azure Managed Identity by using the Cloud Credential Operator (CCO).
|`"true"` or `"false"`
|`features.operators.openshift.io/token-auth-gcp`
|Specify whether an Operator supports configuration for tokenized authentication with Google Cloud APIs via GCP Workload Identity Foundation (WIF) by using the Cloud Credential Operator (CCO).
|`"true"` or `"false"`
|`features.operators.openshift.io/cnf`
|Specify whether an Operator provides a Cloud-Native Network Function (CNF) Kubernetes plugin.
|`"true"` or `"false"`
|`features.operators.openshift.io/cni`
|Specify whether an Operator provides a Container Network Interface (CNI) Kubernetes plugin.
|`"true"` or `"false"`
|`features.operators.openshift.io/csi`
|Specify whether an Operator provides a Container Storage Interface (CSI) Kubernetes plugin.
|`"true"` or `"false"`
|===
[.small]
--
1. Valid values are shown intentionally with double quotes, because Kubernetes annotations must be strings.
--
.Example CSV with infrastructure feature annotations
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
annotations:
features.operators.openshift.io/disconnected: "true"
features.operators.openshift.io/fips-compliant: "false"
features.operators.openshift.io/proxy-aware: "false"
features.operators.openshift.io/tls-profiles: "false"
features.operators.openshift.io/token-auth-aws: "false"
features.operators.openshift.io/token-auth-azure: "false"
features.operators.openshift.io/token-auth-gcp: "false"
----

53
modules/osdk-csv-annotations-other.adoc
View File

@@ -1,53 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-csv-annotations-other_{context}"]
= Other optional annotations
The following Operator annotations are optional.
.Other optional annotations
[cols="5a,5a",options="header"]
|===
|Annotation |Description
|`alm-examples`
|Provide custom resource definition (CRD) templates with a minimum set of configuration. Compatible UIs pre-fill this template for users to further customize.
|`operatorframework.io/initialization-resource`
|Specify a single required custom resource by adding `operatorframework.io/initialization-resource` annotation to the cluster service version (CSV) during Operator installation. The user is then prompted to create the custom resource through a template provided in the CSV. Must include a template that contains a complete YAML definition.
|`operatorframework.io/suggested-namespace`
|Set a suggested namespace where the Operator should be deployed.
|`operatorframework.io/suggested-namespace-template`
|Set a manifest for a `Namespace` object with the default node selector for the namespace specified.
|`operators.openshift.io/valid-subscription`
|Free-form array for listing any specific subscriptions that are required to use the Operator. For example, `'["3Scale Commercial License", "Red Hat Managed Integration"]'`.
|`operators.operatorframework.io/internal-objects`
|Hides CRDs in the UI that are not meant for user manipulation.
|===
.Example CSV with an {product-title} license requirement
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
annotations:
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
----
.Example CSV with a 3scale license requirement
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
annotations:
operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'
----

21
modules/osdk-csv-bundle-files.adoc
View File

@@ -1,21 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-csv-bundle-files_{context}"]
= Generated files and resources
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:
Role:: Defines Operator permissions within a namespace.
ClusterRole:: Defines cluster-wide Operator permissions.
Deployment:: Defines how an Operand of an Operator is run in pods.
CustomResourceDefinition (CRD):: Defines custom resources that your Operator reconciles.
Custom resource examples:: Examples of resources adhering to the spec of a particular CRD.

22
modules/osdk-csv-composition-configuration.adoc
View File

@@ -1,22 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-configuring-csv-composition_{context}"]
= CSV composition configuration
Operator authors can configure CSV composition by populating several fields in the `deploy/olm-catalog/csv-config.yaml` file:
[cols="2a,8a",options="header"]
|===
|Field |Description
|`operator-path` (string)
|The Operator resource manifest file path. Default: `deploy/operator.yaml`.
|`crd-cr-path-list` (string(, string)*)
|A list of CRD and CR manifest file paths. Default: `[deploy/crds/*_{crd,cr}.yaml]`.
|`rbac-path-list` (string(, string)*)
|A list of RBAC role manifest file paths. Default: `[deploy/role.yaml]`.
|===

8
modules/osdk-csv-manual-annotations.adoc
View File

@@ -1,8 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-csv-manual-annotations_{context}"]
= Operator metadata annotations
Operator developers can set certain annotations in the metadata of a cluster service version (CSV) to enable features or highlight capabilities in user interfaces (UIs), such as OperatorHub or the link:https://catalog.redhat.com/software/search?deployed_as=Operator[Red Hat Ecosystem Catalog]. Operator metadata annotations are manually defined by setting the `metadata.annotations` field in the CSV YAML file.

10
modules/osdk-csv-ver.adoc
View File

@@ -1,10 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-csv-ver_{context}"]
= Version management
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.

70
modules/osdk-deploy-olm.adoc
View File

@@ -1,70 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc
// * operators/operator_sdk/osdk-working-bundle-images.adoc
ifeval::["{context}" == "osdk-golang-tutorial"]
:golang:
endif::[]
ifeval::["{context}" == "osdk-working-bundle-images"]
:golang:
endif::[]
:_mod-docs-content-type: PROCEDURE
[id="osdk-deploy-olm_{context}"]
= Deploying an Operator with Operator Lifecycle Manager
Operator Lifecycle Manager (OLM) helps you to install, update, and manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on {product-title} and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (`oc`) for all Operator lifecycle management functions without any additional tools.
The Operator bundle format is the default packaging method for Operator SDK and OLM. You can use the Operator SDK to quickly run a bundle image on OLM to ensure that it runs properly.
.Prerequisites
- Operator SDK CLI installed on a development workstation
- Operator bundle image built and pushed to a registry
- OLM installed on a Kubernetes-based cluster (v1.16.0 or later if you use `apiextensions.k8s.io/v1` CRDs, for example {product-title} {product-version})
ifndef::openshift-dedicated,openshift-rosa[]
- Logged in to the cluster with `oc` using an account with `cluster-admin` permissions
endif::openshift-dedicated,openshift-rosa[]
ifdef::openshift-dedicated,openshift-rosa[]
- Logged in to the cluster with `oc` using an account with `dedicated-admin` permissions
endif::openshift-dedicated,openshift-rosa[]
ifdef::golang[]
- If your Operator is Go-based, your project must be updated to use supported images for running on {product-title}
endif::[]
.Procedure
* Enter the following command to run the Operator on the cluster:
+
[source,terminal]
----
$ operator-sdk run bundle \//<1>
-n <namespace> \//<2>
<registry>/<user>/<bundle_image_name>:<tag> <3>
----
<1> The `run bundle` command creates a valid file-based catalog and installs the Operator bundle on your cluster using OLM.
<2> Optional: By default, the command installs the Operator in the currently active project in your `~/.kube/config` file. You can add the `-n` flag to set a different namespace scope for the installation.
<3> If you do not specify an image, the command uses `quay.io/operator-framework/opm:latest` as the default index image. If you specify an image, the command uses the bundle image itself as the index image.
+
[IMPORTANT]
====
As of {product-title} 4.11, the `run bundle` command supports the file-based catalog format for Operator catalogs by default. The deprecated SQLite database format for Operator catalogs continues to be supported; however, it will be removed in a future release. It is recommended that Operator authors migrate their workflows to the file-based catalog format.
====
+
This command performs the following actions:
+
--
* Create an index image referencing your bundle image. The index image is opaque and ephemeral, but accurately reflects how a bundle would be added to a catalog in production.
* Create a catalog source that points to your new index image, which enables OperatorHub to discover your Operator.
* Deploy your Operator to your cluster by creating an `OperatorGroup`, `Subscription`, `InstallPlan`, and all other required resources, including RBAC.
--
ifeval::["{context}" == "osdk-golang-tutorial"]
:!golang:
endif::[]
ifeval::["{context}" == "osdk-working-bundle-images"]
:!golang:
endif::[]

65
modules/osdk-ensuring-operator-workloads-run-restricted-psa.adoc
View File

@@ -1,65 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-complying-with-psa.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-ensuring-operator-workloads-run-restricted-psa_{context}"]
= Ensuring Operator workloads run in namespaces set to the restricted pod security level
To ensure your Operator project can run on a wide variety of deployments and environments, configure the Operator's workloads to run in namespaces set to the `restricted` pod security level.
[WARNING]
====
You must leave the `runAsUser` field empty. If your image requires a specific user, it cannot be run under restricted security context constraints (SCC) and restricted pod security enforcement.
====
.Procedure
* To configure Operator workloads to run in namespaces set to the `restricted` pod security level, edit your Operator's namespace definition similar to the following examples:
+
[IMPORTANT]
====
It is recommended that you set the seccomp profile in your Operator's namespace definition. However, setting the seccomp profile is not supported in {product-title} 4.10.
====
** For Operator projects that must run in only {product-title} 4.11 and later, edit your Operator's namespace definition similar to the following example:
+
.Example `config/manager/manager.yaml` file
[source,yaml]
----
...
spec:
securityContext:
seccompProfile:
type: RuntimeDefault <1>
runAsNonRoot: true
containers:
- name: <operator_workload_container>
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
...
----
<1> By setting the seccomp profile type to `RuntimeDefault`, the SCC defaults to the pod security profile of the namespace.
** For Operator projects that must also run in {product-title} 4.10, edit your Operator's namespace definition similar to the following example:
+
.Example `config/manager/manager.yaml` file
[source,yaml]
----
...
spec:
securityContext: <1>
runAsNonRoot: true
containers:
- name: <operator_workload_container>
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
...
----
<1> Leaving the seccomp profile type unset ensures your Operator project can run in {product-title} 4.10.

23
modules/osdk-generating-a-csv.adoc
View File

@@ -1,23 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-generating-csvs.adoc
[id="osdk-generating-a-csv_{context}"]
= Generating a CSV
.Prerequisites
- An Operator project generated using the Operator SDK
.Procedure
. In your Operator project, configure your CSV composition by modifying the `deploy/olm-catalog/csv-config.yaml` file, if desired.
. Generate the CSV:
+
[source,terminal]
----
$ operator-sdk generate csv --csv-version <version>
----
. In the new CSV generated in the `deploy/olm-catalog/` directory, ensure all required, manually-defined fields are set appropriately.

29
modules/osdk-golang-controller-configs.adoc
View File

@@ -1,29 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
[id="osdk-golang-controller-configs_{context}"]
= Controller configurations
You can initialize a controller by using many other useful configurations. For example:
* Set the maximum number of concurrent reconciles for the controller by using the `MaxConcurrentReconciles` option, which defaults to `1`:
+
[source,go]
----
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&cachev1.Memcached{}).
Owns(&appsv1.Deployment{}).
WithOptions(controller.Options{
MaxConcurrentReconciles: 2,
}).
Complete(r)
}
----
* Filter watch events using predicates.
* Choose the type of link:https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/handler#EventHandler[EventHandler] to change how a watch event translates to reconcile requests for the reconcile loop. For Operator relationships that are more complex than primary and secondary resources, you can use the `EnqueueRequestsFromMapFunc` handler to transform a watch event into an arbitrary set of reconcile requests.
For more details on these and other configurations, see the upstream link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/builder#example-Builder[Builder] and link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller[Controller] GoDocs.

23
modules/osdk-golang-controller-rbac-markers.adoc
View File

@@ -1,23 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
[id="osdk-golang-controller-rbac-markers_{context}"]
= Permissions and RBAC manifests
The controller requires certain RBAC permissions to interact with the resources it manages. These are specified using RBAC markers, such as the following:
[source,go]
----
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list;
func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
...
}
----
The `ClusterRole` object manifest at `config/rbac/role.yaml` is generated from the previous markers by using the `controller-gen` utility whenever the `make manifests` command is run.

54
modules/osdk-golang-controller-reconcile-loop.adoc
View File

@@ -1,54 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
[id="osdk-golang-controller-reconcile-loop_{context}"]
= Reconcile loop
Every controller has a reconciler object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the `Request` argument, which is a namespace and name key used to find the primary resource object, `Memcached`, from the cache:
[source,go]
----
import (
ctrl "sigs.k8s.io/controller-runtime"
cachev1 "github.com/example-inc/memcached-operator/api/v1"
...
)
func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
// Lookup the Memcached instance for this reconcile request
memcached := &cachev1.Memcached{}
err := r.Get(ctx, req.NamespacedName, memcached)
...
}
----
Based on the return values, result, and error, the request might be requeued and the reconcile loop might be triggered again:
[source,go]
----
// Reconcile successful - don't requeue
return ctrl.Result{}, nil
// Reconcile failed due to error - requeue
return ctrl.Result{}, err
// Requeue for any reason other than an error
return ctrl.Result{Requeue: true}, nil
----
You can set the `Result.RequeueAfter` to requeue the request after a grace period as well:
[source,go]
----
import "time"
// Reconcile for any reason other than an error after 5 seconds
return ctrl.Result{RequeueAfter: time.Second*5}, nil
----
[NOTE]
====
You can return `Result` with `RequeueAfter` set to periodically reconcile a CR.
====
For more on reconcilers, clients, and interacting with resource events, see the link:https://sdk.operatorframework.io/docs/building-operators/golang/references/client/[Controller Runtime Client API] documentation.

30
modules/osdk-golang-controller-resources.adoc
View File

@@ -1,30 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
[id="osdk-golang-controller-resources_{context}"]
= Resources watched by the controller
The `SetupWithManager()` function in `controllers/memcached_controller.go` specifies how the controller is built to watch a CR and other resources that are owned and managed by that controller.
[source,go]
----
import (
...
appsv1 "k8s.io/api/apps/v1"
...
)
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&cachev1.Memcached{}).
Owns(&appsv1.Deployment{}).
Complete(r)
}
----
`NewControllerManagedBy()` provides a controller builder that allows various controller configurations.
`For(&cachev1.Memcached{})` specifies the `Memcached` type as the primary resource to watch. For each Add, Update, or Delete event for a `Memcached` type, the reconcile loop is sent a reconcile `Request` argument, which consists of a namespace and name key, for that `Memcached` object.
`Owns(&appsv1.Deployment{})` specifies the `Deployment` type as the secondary resource to watch. For each `Deployment` type Add, Update, or Delete event, the event handler maps each event to a reconcile request for the owner of the deployment. In this case, the owner is the `Memcached` object for which the deployment was created.

42
modules/osdk-golang-create-api-controller.adoc
View File

@@ -1,42 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-golang-create-api-controller_{context}"]
= Creating an API and controller
Use the Operator SDK CLI to create a custom resource definition (CRD) API and controller.
.Procedure
. Run the following command to create an API with group `cache`, version, `v1`, and kind `Memcached`:
+
[source,terminal]
----
$ operator-sdk create api \
--group=cache \
--version=v1 \
--kind=Memcached
----
. When prompted, enter `y` for creating both the resource and controller:
+
[source,terminal]
----
Create Resource [y/n]
y
Create Controller [y/n]
y
----
+
.Example output
[source,terminal]
----
Writing scaffold for you to edit...
api/v1/memcached_types.go
controllers/memcached_controller.go
...
----
This process generates the `Memcached` resource API at `api/v1/memcached_types.go` and the controller at `controllers/memcached_controller.go`.

43
modules/osdk-golang-define-api.adoc
View File

@@ -1,43 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-golang-define-api_{context}"]
= Defining the API
Define the API for the `Memcached` custom resource (CR).
.Procedure
. Modify the Go type definitions at `api/v1/memcached_types.go` to have the following `spec` and `status`:
+
[source,go]
----
// MemcachedSpec defines the desired state of Memcached
type MemcachedSpec struct {
// +kubebuilder:validation:Minimum=0
// Size is the size of the memcached deployment
Size int32 `json:"size"`
}
// MemcachedStatus defines the observed state of Memcached
type MemcachedStatus struct {
// Nodes are the names of the memcached pods
Nodes []string `json:"nodes"`
}
----
. Update the generated code for the resource type:
+
[source,terminal]
----
$ make generate
----
+
[TIP]
====
After you modify a `*_types.go` file, you must run the `make generate` command to update the generated code for that resource type.
====
+
The above Makefile target invokes the `controller-gen` utility to update the `api/v1/zz_generated.deepcopy.go` file. This ensures your API Go type definitions implement the `runtime.Object` interface that all Kind types must implement.

20
modules/osdk-golang-generate-crd.adoc
View File

@@ -1,20 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-golang-generate-crd_{context}"]
= Generating CRD manifests
After the API is defined with `spec` and `status` fields and custom resource definition (CRD) validation markers, you can generate CRD manifests.
.Procedure
* Run the following command to generate and update CRD manifests:
+
[source,terminal]
----
$ make manifests
----
+
This Makefile target invokes the `controller-gen` utility to generate the CRD manifests in the `config/crd/bases/cache.example.com_memcacheds.yaml` file.

227
modules/osdk-golang-implement-controller.adoc
View File

@@ -1,227 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: PROCEDURE
[id="osdk-golang-implement-controller_{context}"]
= Implementing the controller
After creating a new API and controller, you can implement the controller logic.
.Procedure
* For this example, replace the generated controller file `controllers/memcached_controller.go` with following example implementation:
+
.Example `memcached_controller.go`
[%collapsible]
====
[source,golang]
----
/*
Copyright 2020.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package controllers
import (
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
"k8s.io/apimachinery/pkg/api/errors"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/types"
"reflect"
"context"
"github.com/go-logr/logr"
"k8s.io/apimachinery/pkg/runtime"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
ctrllog "sigs.k8s.io/controller-runtime/pkg/log"
cachev1 "github.com/example-inc/memcached-operator/api/v1"
)
// MemcachedReconciler reconciles a Memcached object
type MemcachedReconciler struct {
client.Client
Log logr.Logger
Scheme *runtime.Scheme
}
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list;
// Reconcile is part of the main kubernetes reconciliation loop which aims to
// move the current state of the cluster closer to the desired state.
// TODO(user): Modify the Reconcile function to compare the state specified by
// the Memcached object against the actual cluster state, and then
// perform operations to make the cluster state reflect the state specified by
// the user.
//
// For more details, check Reconcile and its Result here:
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.7.0/pkg/reconcile
func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
//log := r.Log.WithValues("memcached", req.NamespacedName)
log := ctrllog.FromContext(ctx)
// Fetch the Memcached instance
memcached := &cachev1.Memcached{}
err := r.Get(ctx, req.NamespacedName, memcached)
if err != nil {
if errors.IsNotFound(err) {
// Request object not found, could have been deleted after reconcile request.
// Owned objects are automatically garbage collected. For additional cleanup logic use finalizers.
// Return and don't requeue
log.Info("Memcached resource not found. Ignoring since object must be deleted")
return ctrl.Result{}, nil
}
// Error reading the object - requeue the request.
log.Error(err, "Failed to get Memcached")
return ctrl.Result{}, err
}
// Check if the deployment already exists, if not create a new one
found := &appsv1.Deployment{}
err = r.Get(ctx, types.NamespacedName{Name: memcached.Name, Namespace: memcached.Namespace}, found)
if err != nil && errors.IsNotFound(err) {
// Define a new deployment
dep := r.deploymentForMemcached(memcached)
log.Info("Creating a new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
err = r.Create(ctx, dep)
if err != nil {
log.Error(err, "Failed to create new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
return ctrl.Result{}, err
}
// Deployment created successfully - return and requeue
return ctrl.Result{Requeue: true}, nil
} else if err != nil {
log.Error(err, "Failed to get Deployment")
return ctrl.Result{}, err
}
// Ensure the deployment size is the same as the spec
size := memcached.Spec.Size
if *found.Spec.Replicas != size {
found.Spec.Replicas = &size
err = r.Update(ctx, found)
if err != nil {
log.Error(err, "Failed to update Deployment", "Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)
return ctrl.Result{}, err
}
// Spec updated - return and requeue
return ctrl.Result{Requeue: true}, nil
}
// Update the Memcached status with the pod names
// List the pods for this memcached's deployment
podList := &corev1.PodList{}
listOpts := []client.ListOption{
client.InNamespace(memcached.Namespace),
client.MatchingLabels(labelsForMemcached(memcached.Name)),
}
if err = r.List(ctx, podList, listOpts...); err != nil {
log.Error(err, "Failed to list pods", "Memcached.Namespace", memcached.Namespace, "Memcached.Name", memcached.Name)
return ctrl.Result{}, err
}
podNames := getPodNames(podList.Items)
// Update status.Nodes if needed
if !reflect.DeepEqual(podNames, memcached.Status.Nodes) {
memcached.Status.Nodes = podNames
err := r.Status().Update(ctx, memcached)
if err != nil {
log.Error(err, "Failed to update Memcached status")
return ctrl.Result{}, err
}
}
return ctrl.Result{}, nil
}
// deploymentForMemcached returns a memcached Deployment object
func (r *MemcachedReconciler) deploymentForMemcached(m *cachev1.Memcached) *appsv1.Deployment {
ls := labelsForMemcached(m.Name)
replicas := m.Spec.Size
dep := &appsv1.Deployment{
ObjectMeta: metav1.ObjectMeta{
Name: m.Name,
Namespace: m.Namespace,
},
Spec: appsv1.DeploymentSpec{
Replicas: &replicas,
Selector: &metav1.LabelSelector{
MatchLabels: ls,
},
Template: corev1.PodTemplateSpec{
ObjectMeta: metav1.ObjectMeta{
Labels: ls,
},
Spec: corev1.PodSpec{
Containers: []corev1.Container{{
Image: "memcached:1.4.36-alpine",
Name: "memcached",
Command: []string{"memcached", "-m=64", "-o", "modern", "-v"},
Ports: []corev1.ContainerPort{{
ContainerPort: 11211,
Name: "memcached",
}},
}},
},
},
},
}
// Set Memcached instance as the owner and controller
ctrl.SetControllerReference(m, dep, r.Scheme)
return dep
}
// labelsForMemcached returns the labels for selecting the resources
// belonging to the given memcached CR name.
func labelsForMemcached(name string) map[string]string {
return map[string]string{"app": "memcached", "memcached_cr": name}
}
// getPodNames returns the pod names of the array of pods passed in
func getPodNames(pods []corev1.Pod) []string {
var podNames []string
for _, pod := range pods {
podNames = append(podNames, pod.Name)
}
return podNames
}
// SetupWithManager sets up the controller with the Manager.
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&cachev1.Memcached{}).
Owns(&appsv1.Deployment{}).
Complete(r)
}
----
====
+
The example controller runs the following reconciliation logic for each `Memcached` custom resource (CR):
+
--
* Create a Memcached deployment if it does not exist.
* Ensure that the deployment size is the same as specified by the `Memcached` CR spec.
* Update the `Memcached` CR status with the names of the `memcached` pods.
--

35
modules/osdk-golang-manager.adoc
View File

@@ -1,35 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-golang-manager_{context}"]
= About the Manager
The main program for the Operator is the `main.go` file, which initializes and runs the link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Manager[Manager]. The Manager automatically registers the Scheme for all custom resource (CR) API definitions and sets up and runs controllers and webhooks.
The Manager can restrict the namespace that all controllers watch for resources:
[source,go]
----
mgr, err := ctrl.NewManager(cfg, manager.Options{Namespace: namespace})
----
By default, the Manager watches the namespace where the Operator runs. To watch all namespaces, you can leave the `namespace` option empty:
[source,go]
----
mgr, err := ctrl.NewManager(cfg, manager.Options{Namespace: ""})
----
You can also use the link:https://pkg.go.dev/github.com/kubernetes-sigs/controller-runtime@v0.2.0-alpha.0/pkg/cache#MultiNamespacedCacheBuilder[`MultiNamespacedCacheBuilder`] function to watch a specific set of namespaces:
[source,go]
----
var namespaces []string <1>
mgr, err := ctrl.NewManager(cfg, manager.Options{ <2>
NewCache: cache.MultiNamespacedCacheBuilder(namespaces),
})
----
<1> List of namespaces.
<2> Creates a `Cmd` struct to provide shared dependencies and start components.

30
modules/osdk-golang-multi-group-apis.adoc
View File

@@ -1,30 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-golang-multi-group-apis_{context}"]
= About multi-group APIs
Before you create an API and controller, consider whether your Operator requires multiple API groups. This tutorial covers the default case of a single group API, but to change the layout of your project to support multi-group APIs, you can run the following command:
[source,terminal]
----
$ operator-sdk edit --multigroup=true
----
This command updates the `PROJECT` file, which should look like the following example:
[source,yaml]
----
domain: example.com
layout: go.kubebuilder.io/v3
multigroup: true
...
----
For multi-group projects, the API Go type files are created in the `apis/<group>/<version>/` directory, and the controllers are created in the `controllers/<group>/` directory. The Dockerfile is then updated accordingly.
.Additional resource
* For more details on migrating to a multi-group project, see the link:https://book.kubebuilder.io/migration/multi-group.html[Kubebuilder documentation].

36
modules/osdk-golang-project-layout.adoc
View File

@@ -1,36 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/golang/osdk-golang-project-layout.adoc
[id="osdk-golang-project-layout_{context}"]
= Go-based project layout
Go-based Operator projects, the default type, generated using the `operator-sdk init` command contain the following files and directories:
[options="header",cols="1,4"]
|===
|File or directory |Purpose
|`main.go`
|Main program of the Operator. This instantiates a new manager that registers all custom resource definitions (CRDs) in the `apis/` directory and starts all controllers in the `controllers/` directory.
|`apis/`
|Directory tree that defines the APIs of the CRDs. You must edit the `apis/<version>/<kind>_types.go` files to define the API for each resource type and import these packages in your controllers to watch for these resource types.
|`controllers/`
|Controller implementations. Edit the `controller/<kind>_controller.go` files to define the reconcile logic of the controller for handling a resource type of the specified kind.
|`config/`
|Kubernetes manifests used to deploy your controller on a cluster, including CRDs, RBAC, and certificates.
|`Makefile`
|Targets used to build and deploy your controller.
|`Dockerfile`
|Instructions used by a container engine to build your Operator.
|`manifests/`
|Kubernetes manifests for registering CRDs, setting up RBAC, and deploying the Operator as a deployment.
|===

38
modules/osdk-ha-sno-api-examples.adoc
View File

@@ -1,38 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-ha-sno.adoc
[id="osdk-ha-sno-api-examples_{context}"]
= Example API usage in Operator projects
As an Operator author, you can update your Operator project to access the Infrastructure API by using normal Kubernetes constructs and the `controller-runtime` library, as shown in the following examples:
.`controller-runtime` library example
[source,go]
----
// Simple query
nn := types.NamespacedName{
Name: "cluster",
}
infraConfig := &configv1.Infrastructure{}
err = crClient.Get(context.Background(), nn, infraConfig)
if err != nil {
return err
}
fmt.Printf("using crclient: %v\n", infraConfig.Status.ControlPlaneTopology)
fmt.Printf("using crclient: %v\n", infraConfig.Status.InfrastructureTopology)
----
.Kubernetes constructs example
[source,go]
----
operatorConfigInformer := configinformer.NewSharedInformerFactoryWithOptions(configClient, 2*time.Second)
infrastructureLister = operatorConfigInformer.Config().V1().Infrastructures().Lister()
infraConfig, err := configClient.ConfigV1().Infrastructures().Get(context.Background(), "cluster", metav1.GetOptions{})
if err != nil {
return err
}
// fmt.Printf("%v\n", infraConfig)
fmt.Printf("%v\n", infraConfig.Status.ControlPlaneTopology)
fmt.Printf("%v\n", infraConfig.Status.InfrastructureTopology)
----

19
modules/osdk-ha-sno-api.adoc
View File

@@ -1,19 +0,0 @@
// Module included in the following assemblies:
//
// * operators/operator_sdk/osdk-ha-sno.adoc
:_mod-docs-content-type: CONCEPT
[id="osdk-ha-sno-api_{context}"]
= About the cluster high-availability mode API
{product-title} provides a cluster high-availability mode API that can be used by Operators to help detect infrastructure topology. The Infrastructure API holds cluster-wide information regarding infrastructure. Operators managed by Operator Lifecycle Manager (OLM) can use the Infrastructure API if they need to configure an Operand or managed workload differently based on the high-availability mode.
In the Infrastructure API, the `infrastructureTopology` status expresses the expectations for infrastructure services that do not run on control plane nodes, usually indicated by a node selector for a `role` value other than `master`. The `controlPlaneTopology` status expresses the expectations for Operands that normally run on control plane nodes.
The default setting for either status is `HighlyAvailable`, which represents the behavior Operators have in multiple node clusters. The `SingleReplica` setting is used in single-node clusters, also known as {sno}, and indicates that Operators should not configure their Operands for high-availability operation.
The {product-title} installer sets the `controlPlaneTopology` and `infrastructureTopology` status fields based on the replica counts for the cluster when it is created, according to the following rules:
* When the control plane replica count is less than 3, the `controlPlaneTopology` status is set to `SingleReplica`. Otherwise, it is set to `HighlyAvailable`.
* When the worker replica count is 0, the control plane nodes are also configured as workers. Therefore, the `infrastructureTopology` status will be the same as the `controlPlaneTopology` status.
* When the worker replica count is 1, the `infrastructureTopology` is set to `SingleReplica`. Otherwise, it is set to `HighlyAvailable`.

Some files were not shown because too many files have changed in this diff Show More