Skip to content

Commit 2eb5fad

Browse files
adellapeadellape
authored
Merge pull request #69171 from adellape/anno
OSDOCS#9025: Add new infra annotations for Operators
2 parents edf83b0 + 0b74a72 commit 2eb5fad

File tree

5 files changed

+196
-77
lines changed

5 files changed

+196
-77
lines changed

‎modules/osdk-csv-annotations-dep.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-generating-csvs.adoc
4+
5+
[id="osdk-csv-manual-annotations-deprecated_{context}"]
6+
= Deprecated annotations
7+
8+
The following Operator annotations are deprecated.
9+
10+
[discrete]
11+
== operators.openshift.io/infrastructure-features
12+
13+
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.
14+
15+
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].
16+
17+
.Deprecated `operators.openshift.io/infrastructure-features` annotations
18+
[cols="2a,4a",options="header"]
19+
|===
20+
|Valid annotation values |Description
21+
22+
|`disconnected`
23+
|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.
24+
25+
|`cnf`
26+
|Operator provides a Cloud-native Network Functions (CNF) Kubernetes plugin.
27+
28+
|`cni`
29+
|Operator provides a Container Network Interface (CNI) Kubernetes plugin.
30+
31+
|`csi`
32+
|Operator provides a Container Storage Interface (CSI) Kubernetes plugin.
33+
34+
|`fips`
35+
|Operator accepts the FIPS mode of the underlying platform and works on nodes that are booted into FIPS mode.
36+
37+
[IMPORTANT]
38+
====
39+
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.
40+
====
41+
42+
|`proxy-aware`
43+
|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.
44+
|===
45+
46+
.Example CSV with `disconnected` and `proxy-aware` support
47+
[source,yaml]
48+
----
49+
apiVersion: operators.coreos.com/v1alpha1
50+
kind: ClusterServiceVersion
51+
metadata:
52+
annotations:
53+
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
54+
----

‎modules/osdk-csv-annotations-infra.adoc

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-generating-csvs.adoc
4+
5+
[id="osdk-csv-annotations-infra_{context}"]
6+
= Infrastructure features annotations
7+
8+
The following Operator annotations detail the infrastructure features that an Operator might support, denoted with 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].
9+
10+
[NOTE]
11+
====
12+
The following infrastructure feature annotations are supported in {product-title} 4.10 and later.
13+
====
14+
15+
.Infrastructure features annotations
16+
[cols="4a,5a,3a,options="header"]
17+
|===
18+
|Annotation |Description |Valid values
19+
20+
|`features.operators.openshift.io/disconnected`
21+
|Specify whether an Operator leverages the `spec.relatedImages` CSV field and can run without an internet connection by referring to any related image by its digest.
22+
|`true` or `false`
23+
24+
|`features.operators.openshift.io/fips-compliant`
25+
|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.
26+
|`true` or `false`
27+
28+
|`features.operators.openshift.io/proxy-aware`
29+
|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).
30+
|`true` or `false`
31+
32+
|`features.operators.openshift.io/tls-profiles`
33+
|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).
34+
|`true` or `false`
35+
36+
|`features.operators.openshift.io/token-auth-aws`
37+
|Specify whether an Operator supports configuration for tokenzied authentication with AWS APIs via AWS Secure Token Service (STS) by using the Cloud Credential Operator (CCO).
38+
|`true` or `false`
39+
40+
|`features.operators.openshift.io/token-auth-azure`
41+
|Specify whether an Operator supports configuration for tokenzied authentication with Azure APIs via Azure Managed Identity by using the Cloud Credential Operator (CCO).
42+
|`true` or `false`
43+
44+
|`features.operators.openshift.io/token-auth-gcp`
45+
|Specify whether an Operator supports configuration for tokenzied authentication with Google Cloud APIs via GCP Workload Identity Foundation (WIF) by using the Cloud Credential Operator (CCO).
46+
|`true` or `false`
47+
48+
|`features.operators.openshift.io/cnf`
49+
|Specify whether an Operator provides a Cloud-Native Network Function (CNF) Kubernetes plugin.
50+
|`true` or `false`
51+
52+
|`features.operators.openshift.io/cni`
53+
|Specify whether an Operator provides a Container Network Interface (CNI) Kubernetes plugin.
54+
|`true` or `false`
55+
56+
|`features.operators.openshift.io/csi`
57+
|Specify whether an Operator provides a Container Storage Interface (CSI) Kubernetes plugin.
58+
|`true` or `false`
59+
60+
|===
61+
62+
.Example CSV with infrastructure feature annotations
63+
[source,yaml]
64+
----
65+
apiVersion: operators.coreos.com/v1alpha1
66+
kind: ClusterServiceVersion
67+
metadata:
68+
annotations:
69+
features.operators.openshift.io/disconnected: "true"
70+
features.operators.openshift.io/fips-compliant: "false"
71+
features.operators.openshift.io/proxy-aware: "false"
72+
features.operators.openshift.io/tls-profiles: "false"
73+
features.operators.openshift.io/token-auth-aws: "false"
74+
features.operators.openshift.io/token-auth-azure: "false"
75+
features.operators.openshift.io/token-auth-gcp: "false"
76+
----

‎modules/osdk-csv-annotations-other.adoc

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-generating-csvs.adoc
4+
5+
[id="osdk-csv-annotations-other_{context}"]
6+
= Other optional annotations
7+
8+
The following Operator annotations are optional.
9+
10+
.Other optional annotations
11+
[cols="5a,5a",options="header"]
12+
|===
13+
|Annotation |Description
14+
15+
|`alm-examples`
16+
|Provide custom resource definition (CRD) templates with a minimum set of configuration. Compatible UIs pre-fill this template for users to further customize.
17+
18+
|`operatorframework.io/initialization-resource`
19+
|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.
20+
21+
|`operatorframework.io/suggested-namespace`
22+
|Set a suggested namespace where the Operator should be deployed.
23+
24+
|`operatorframework.io/suggested-namespace-template`
25+
|Set a manifest for a `Namespace` object with the default node selector for the namespace specified.
26+
27+
|`operators.openshift.io/valid-subscription`
28+
|Free-form array for listing any specific subscriptions that are required to use the Operator. For example, `'["3Scale Commercial License", "Red Hat Managed Integration"]'`.
29+
30+
|`operators.operatorframework.io/internal-objects`
31+
|Hides CRDs in the UI that are not meant for user manipulation.
32+
33+
|===
34+
35+
.Example CSV with an {product-title} license requirement
36+
[source,yaml]
37+
----
38+
apiVersion: operators.coreos.com/v1alpha1
39+
kind: ClusterServiceVersion
40+
metadata:
41+
annotations:
42+
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
43+
----
44+
45+
.Example CSV with a 3scale license requirement
46+
[source,yaml]
47+
----
48+
apiVersion: operators.coreos.com/v1alpha1
49+
kind: ClusterServiceVersion
50+
metadata:
51+
annotations:
52+
operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'
53+
----

‎modules/osdk-csv-manual-annotations.adoc

Lines changed: 1 addition & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -5,75 +5,4 @@
55
[id="osdk-csv-manual-annotations_{context}"]
66
= Operator metadata annotations
77

8-
Operator developers can manually define certain annotations in the metadata of a cluster service version (CSV) to enable features or highlight capabilities in user interfaces (UIs), such as OperatorHub.
9-
10-
The following table lists Operator metadata annotations that can be manually defined using `metadata.annotations` fields.
11-
12-
.Annotations
13-
[cols="5a,5a",options="header"]
14-
|===
15-
|Field |Description
16-
17-
|`alm-examples`
18-
|Provide custom resource definition (CRD) templates with a minimum set of configuration. Compatible UIs pre-fill this template for users to further customize.
19-
20-
|`operatorframework.io/initialization-resource`
21-
|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.
22-
23-
|`operatorframework.io/suggested-namespace`
24-
|Set a suggested namespace where the Operator should be deployed.
25-
26-
|`operatorframework.io/suggested-namespace-template`
27-
|Set a manifest for a Namespace object with the namespace default node selector specified.
28-
29-
|`operators.openshift.io/infrastructure-features`
30-
|Infrastructure features supported by the Operator. Users can view and filter by these features when discovering Operators through OperatorHub in the web console. Valid, case-sensitive values:
31-
32-
- `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.
33-
- `cnf`: Operator provides a Cloud-native Network Functions (CNF) Kubernetes plugin.
34-
- `cni`: Operator provides a Container Network Interface (CNI) Kubernetes plugin.
35-
- `csi`: Operator provides a Container Storage Interface (CSI) Kubernetes plugin.
36-
- `fips`: Operator accepts the FIPS mode of the underlying platform and works on nodes that are booted into FIPS mode.
37-
38-
[IMPORTANT]
39-
====
40-
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.
41-
====
42-
- `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.
43-
44-
|`operators.openshift.io/valid-subscription`
45-
|Free-form array for listing any specific subscriptions that are required to use the Operator. For example, `'["3Scale Commercial License", "Red Hat Managed Integration"]'`.
46-
47-
|`operators.operatorframework.io/internal-objects`
48-
|Hides CRDs in the UI that are not meant for user manipulation.
49-
50-
|===
51-
52-
[discrete]
53-
[id="osdk-csv-manual-annotations-examples_{context}"]
54-
== Example use cases
55-
56-
.Operator supports disconnected and proxy-aware
57-
[source,terminal]
58-
----
59-
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
60-
----
61-
62-
.Operator requires an {product-title} license
63-
[source,terminal]
64-
----
65-
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
66-
----
67-
68-
.Operator requires a 3scale license
69-
[source,terminal]
70-
----
71-
operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'
72-
----
73-
74-
.Operator supports disconnected and proxy-aware, and requires an {product-title} license
75-
[source,terminal]
76-
----
77-
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
78-
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
79-
----
8+
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.

‎operators/operator_sdk/osdk-generating-csvs.adoc

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,19 +30,26 @@ include::modules/osdk-manually-defined-csv-fields.adoc[leveloffset=+1]
3030

3131
* xref:../../operators/understanding/olm-what-operators-are.adoc#olm-maturity-model_olm-what-operators-are[Operator maturity model]
3232
33-
include::modules/osdk-csv-manual-annotations.adoc[leveloffset=+2]
33+
include::modules/osdk-csv-manual-annotations.adoc[leveloffset=+1]
34+
include::modules/osdk-csv-annotations-infra.adoc[leveloffset=+2]
35+
[role="_additional-resources"]
36+
.Additional resources
37+
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-enabling-operator-for-restricted-network_osdk-generating-csvs[Enabling your Operator for restricted network environments] (disconnected mode)
38+
ifndef::openshift-dedicated,openshift-rosa[]
39+
* xref:../../installing/installing-fips.adoc#installing-fips[Support for FIPS cryptography]
40+
endif::openshift-dedicated,openshift-rosa[]
3441
42+
include::modules/osdk-csv-annotations-other.adoc[leveloffset=+2]
3543
[role="_additional-resources"]
3644
.Additional resources
3745
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-crds-templates_osdk-generating-csvs[CRD templates]
3846
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-init-resource_osdk-generating-csvs[Initializing required custom resources]
3947
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-suggested-namespace_osdk-generating-csvs[Setting a suggested namespace]
4048
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-suggested-namespace-default-node_osdk-generating-csvs[Setting a suggested namespace with default node selector]
41-
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-enabling-operator-for-restricted-network_osdk-generating-csvs[Enabling your Operator for restricted network environments] (disconnected mode)
4249
* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-hiding-internal-objects_osdk-generating-csvs[Hiding internal objects]
43-
ifndef::openshift-dedicated,openshift-rosa[]
44-
* xref:../../installing/installing-fips.adoc#installing-fips[Support for FIPS crytography]
45-
endif::openshift-dedicated,openshift-rosa[]
50+
51+
include::modules/osdk-csv-annotations-dep.adoc[leveloffset=+2]
52+
4653
4754
include::modules/olm-enabling-operator-restricted-network.adoc[leveloffset=+1]
4855
include::modules/olm-enabling-operator-for-multi-arch.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)