From 1ca2c9985ad45b9b2c76f6659c33381b372cada1 Mon Sep 17 00:00:00 2001 From: robszumski Date: Tue, 29 Oct 2019 16:16:13 -0400 Subject: [PATCH 1/5] doc: add internal image proposal --- .../design-proposals/internal-images.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 doc/contributors/design-proposals/internal-images.md diff --git a/doc/contributors/design-proposals/internal-images.md b/doc/contributors/design-proposals/internal-images.md new file mode 100644 index 0000000000..2f7653765f --- /dev/null +++ b/doc/contributors/design-proposals/internal-images.md @@ -0,0 +1,51 @@ +# Related Images + +Status: Pending + +Version: Alpha + +Implementation Owner: unassigned + +# Motivation + +Operators often use CRDs internally. These objects aren't meant for end-users to manipulate and are confusing to end users of the Operator. + +## Proposal + +Introduce a convention for marking these CRDs as "internal", so they can omitted from user interfaces and CLI tools. + +A good example of this is the [Apache CouchDB Operator](https://operatorhub.io/operator/couchdb-operator) which has literally marked the CRD name with the "internal" moniker, eg `(Internal) CouchDB Formation`. + +### Implementation + +#### New CRD annotation + +The behavior is straightforward, when a CRD is managed as part of the Operator installation, it can be marked with an annotation which is available for downstream tools to read and hide the CRD where applicable. This should be backwards compatible as a no-op, so it can be considered progressive enhancement. + +``` +kind: CustomResourceDefinition +apiVersion: apiextensions.k8s.io/v1beta1 +metadata: + name: hivetables.metering.openshift.io + annotations: + operators.coreos.com/internal-object: true +spec: + ... +status + ... +``` + +#### Implementation Stages + +- [ ] Verify annotations are populated down after installation +- [ ] Document this annotation convention + +### User Documentation + +#### Hiding Internal Concepts from End-Users + +It is a common practice for an Operator to utilize CRDs "under the hood" to internally accomplish a task. For example, a database Operator might have a Replication CRD that is created whenever an end-user creates a Database object with `replication: true`. + +If this Replication CRD is not meant for manipulation by end-users, it can be hidden by submitting it's definition with the `operators.coreos.com/internal-object` annotation set to true. + +Before marking one of your CRDs as internal, make sure that any debugging information or configuration that might be required to manage the application is reflected on the CR's status or spec block. From c48c47d95529639e599caf2a70200c13863ff6f4 Mon Sep 17 00:00:00 2001 From: robszumski Date: Thu, 31 Oct 2019 12:57:40 -0400 Subject: [PATCH 2/5] Ammend proposal to include data CRDs and new annotation names. --- .../design-proposals/internal-objects.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 doc/contributors/design-proposals/internal-objects.md diff --git a/doc/contributors/design-proposals/internal-objects.md b/doc/contributors/design-proposals/internal-objects.md new file mode 100644 index 0000000000..6fb577444f --- /dev/null +++ b/doc/contributors/design-proposals/internal-objects.md @@ -0,0 +1,55 @@ +# Related Images + +Status: Pending + +Version: Alpha + +Implementation Owner: unassigned + +# Motivation + +Operators often use CRDs internally. These objects aren't meant for end-users to manipulate and are confusing to end users of the Operator. + +## Proposal + +Introduce a convention for marking these CRDs as "internal" or "data only", so they can omitted from user interfaces and CLI tools. + +A good example of this is the [Apache CouchDB Operator](https://operatorhub.io/operator/couchdb-operator) which has literally marked the CRD name with the "internal" moniker, eg `(Internal) CouchDB Formation`. + +### Implementation + +#### New CRD annotation + +The behavior is straightforward, when a CRD is managed as part of the Operator installation, it can be marked with an annotation which is available for downstream tools to read and hide the CRD where applicable. This should be backwards compatible as a no-op, so it can be considered progressive enhancement. + +``` +kind: CustomResourceDefinition +apiVersion: apiextensions.k8s.io/v1beta1 +metadata: + name: hivetables.metering.openshift.io + annotations: + apps.kubernetes.io/internal-object:true + apps.kubernetes.io/data-object:true +spec: + ... +status + ... +``` + +#### Implementation Stages + +- [ ] Verify annotations are populated down after installation +- [ ] Document this annotation convention +- [ ] Verify that any Operator pipelines allow use of the annotations + +### User Documentation + +#### Hiding Internal Concepts from End-Users + +It is a common practice for an Operator to utilize CRDs "under the hood" to internally accomplish a task. For example, a database Operator might have a Replication CRD that is created whenever an end-user creates a Database object with `replication: true`. + +If this Replication CRD is not meant for manipulation by end-users, it can be hidden by submitting it's definition with the `apps.kubernetes.io/internal-object` annotation set to true. + +If there exists a CRD that is only meant for tracking data, it can also be annotated with `apps.kubernetes.io/data-object` set to true. + +Before marking one of your CRDs as internal, make sure that any debugging information or configuration that might be required to manage the application is reflected on the CR's status or spec block. From 82bd6237df65c685d0bb18b13d3fcae0563bfd8c Mon Sep 17 00:00:00 2001 From: robszumski Date: Thu, 31 Oct 2019 12:59:43 -0400 Subject: [PATCH 3/5] Use the correct title --- doc/contributors/design-proposals/internal-objects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributors/design-proposals/internal-objects.md b/doc/contributors/design-proposals/internal-objects.md index 6fb577444f..aedfe0140b 100644 --- a/doc/contributors/design-proposals/internal-objects.md +++ b/doc/contributors/design-proposals/internal-objects.md @@ -1,4 +1,4 @@ -# Related Images +# Hiding Internal or Data-only Objects Status: Pending From 099fbc5a61e9cd9ef3ba57b91bf699e697436f1e Mon Sep 17 00:00:00 2001 From: robszumski Date: Fri, 1 Nov 2019 10:30:22 -0400 Subject: [PATCH 4/5] Swap annotation namespace --- doc/contributors/design-proposals/internal-objects.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/contributors/design-proposals/internal-objects.md b/doc/contributors/design-proposals/internal-objects.md index aedfe0140b..01eade141c 100644 --- a/doc/contributors/design-proposals/internal-objects.md +++ b/doc/contributors/design-proposals/internal-objects.md @@ -28,8 +28,8 @@ apiVersion: apiextensions.k8s.io/v1beta1 metadata: name: hivetables.metering.openshift.io annotations: - apps.kubernetes.io/internal-object:true - apps.kubernetes.io/data-object:true + operators.operatorframework.io/internal-object:true + operators.operatorframework.io/data-object:true spec: ... status @@ -48,8 +48,8 @@ status It is a common practice for an Operator to utilize CRDs "under the hood" to internally accomplish a task. For example, a database Operator might have a Replication CRD that is created whenever an end-user creates a Database object with `replication: true`. -If this Replication CRD is not meant for manipulation by end-users, it can be hidden by submitting it's definition with the `apps.kubernetes.io/internal-object` annotation set to true. +If this Replication CRD is not meant for manipulation by end-users, it can be hidden by submitting it's definition with the `operators.operatorframework.io/internal-object` annotation set to true. -If there exists a CRD that is only meant for tracking data, it can also be annotated with `apps.kubernetes.io/data-object` set to true. +If there exists a CRD that is only meant for tracking data, it can also be annotated with `operators.operatorframework.io/data-object` set to true. Before marking one of your CRDs as internal, make sure that any debugging information or configuration that might be required to manage the application is reflected on the CR's status or spec block. From 4cc0432a95e6ca5609879af5ecaf45367b113a21 Mon Sep 17 00:00:00 2001 From: Rob Szumski Date: Fri, 1 Nov 2019 10:33:46 -0400 Subject: [PATCH 5/5] Delete file that was renamed --- .../design-proposals/internal-images.md | 51 ------------------- 1 file changed, 51 deletions(-) delete mode 100644 doc/contributors/design-proposals/internal-images.md diff --git a/doc/contributors/design-proposals/internal-images.md b/doc/contributors/design-proposals/internal-images.md deleted file mode 100644 index 2f7653765f..0000000000 --- a/doc/contributors/design-proposals/internal-images.md +++ /dev/null @@ -1,51 +0,0 @@ -# Related Images - -Status: Pending - -Version: Alpha - -Implementation Owner: unassigned - -# Motivation - -Operators often use CRDs internally. These objects aren't meant for end-users to manipulate and are confusing to end users of the Operator. - -## Proposal - -Introduce a convention for marking these CRDs as "internal", so they can omitted from user interfaces and CLI tools. - -A good example of this is the [Apache CouchDB Operator](https://operatorhub.io/operator/couchdb-operator) which has literally marked the CRD name with the "internal" moniker, eg `(Internal) CouchDB Formation`. - -### Implementation - -#### New CRD annotation - -The behavior is straightforward, when a CRD is managed as part of the Operator installation, it can be marked with an annotation which is available for downstream tools to read and hide the CRD where applicable. This should be backwards compatible as a no-op, so it can be considered progressive enhancement. - -``` -kind: CustomResourceDefinition -apiVersion: apiextensions.k8s.io/v1beta1 -metadata: - name: hivetables.metering.openshift.io - annotations: - operators.coreos.com/internal-object: true -spec: - ... -status - ... -``` - -#### Implementation Stages - -- [ ] Verify annotations are populated down after installation -- [ ] Document this annotation convention - -### User Documentation - -#### Hiding Internal Concepts from End-Users - -It is a common practice for an Operator to utilize CRDs "under the hood" to internally accomplish a task. For example, a database Operator might have a Replication CRD that is created whenever an end-user creates a Database object with `replication: true`. - -If this Replication CRD is not meant for manipulation by end-users, it can be hidden by submitting it's definition with the `operators.coreos.com/internal-object` annotation set to true. - -Before marking one of your CRDs as internal, make sure that any debugging information or configuration that might be required to manage the application is reflected on the CR's status or spec block.