github.com/operator-framework/operator-lifecycle-manager@v0.30.0/doc/contributors/design-proposals/internal-objects.md (about)

     1  # Hiding Internal or Data-only Objects
     2  
     3  Status: Pending
     4  
     5  Version: Alpha
     6  
     7  Implementation Owner: unassigned 
     8  
     9  # Motivation
    10  
    11  Operators often use CRDs internally. These objects aren't meant for end-users to manipulate and are confusing to end users of the Operator.
    12  
    13  ## Proposal
    14  
    15  Introduce a convention for marking these CRDs as "internal" or "data only", so they can omitted from user interfaces and CLI tools.
    16  
    17  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`.
    18  
    19  ### Implementation
    20  
    21  #### New CSV annotation
    22  
    23  The behavior is straightforward, when a CRD is managed as part of the Operator installation, it can be marked as managed by the Operator, but also that it is an internal resource, not to be used by an end-user. This is an annotation on the CSV of `spec.owned.customresourcedefinitions.name` names, 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.
    24  
    25  ```
    26  apiVersion: operators.coreos.com/v1alpha1
    27  kind: ClusterServiceVersion
    28  metadata:
    29    name: couchdb-operator-v1.2.3
    30    annotations:
    31      apps.operatorframework.io/internal-objects:
    32        - '(Internal) CouchDB Formation Lock'
    33        - '(Internal) CouchDB Recipe'
    34  spec:
    35    ...
    36  status
    37    ...
    38  ```
    39  
    40  #### Implementation Stages
    41  
    42  - [ ] Verify annotations are populated down after installation
    43  - [ ] Document this annotation convention
    44  - [ ] Verify that any Operator pipelines allow use of the annotations
    45  
    46  ### User Documentation
    47  
    48  #### Hiding Internal Concepts from End-Users
    49  
    50  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`. 
    51  
    52  If this Replication CRD is not meant for manipulation by end-users, it can be hidden by including its name within the `apps.operatorframework.io/internal-objects` annotation's array of values.
    53  
    54  If there exists a CRD that is only meant for tracking data, it can also be included within the  `app.operatorframework.io/data-object` array.
    55  
    56  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.