API Markers

This document describes code markers supported by the SDK.

ClusterServiceVersion markers

This section details ClusterServiceVersion (CSV) code markers and lists available markers.

Note: CSV markers can only be used in Go Operator projects. Annotations for Ansible and Helm Operator projects will be added in the future.

Usage

All CSV markers have the prefix +operator-sdk:csv.

+operator-sdk:csv:customresourcedefinitions

These markers populate owned customresourcedefinitions in your CSV.

Possible type-level markers:

  • +operator-sdk:csv:customresourcedefinitions:displayName="some display name"
    • Configures the kind’s display name.
  • +operator-sdk:csv:customresourcedefinitions:resources={{Kind1,v1alpha1,dns-name-1},{Kind2,v1,"dns-name-2"},...}
    • Configures the kind’s resources.
  • +operator-sdk:csv:customresourcedefinitions:order=1
    • Configures the order of this type in the list. Markers with order omitted have the highest order, i.e. are at the end of the list. If more than one marker has the same order, the corresponding descriptions will be sorted alphabetically and placed above others with higher orders. Pre-existing list elements in the CSV will be appended to the set of other elements in the order corresponding to its index.

Possible field-level markers, all of which must contain the type=[spec,status] key-value pair:

  • +operator-sdk:csv:customresourcedefinitions:type=[spec,status],displayName="some field display name"
    • Configures the field’s display name.
  • +operator-sdk:csv:customresourcedefinitions:type=[spec,status],xDescriptors={"urn:alm:descriptor:com.tectonic.ui:podCount","urn:alm:descriptor:io.kubernetes:custom"}
    • Configures the field’s x-descriptors.
  • +operator-sdk:csv:customresourcedefinitions:type=[spec,status],order=1
    • Configures the order of this type in the list. Markers with order omitted have the highest order, i.e. are at the end of the list. If more than one marker has the same order, the corresponding descriptions will be sorted alphabetically and placed above others with higher orders.

Top-level kind, name, and version fields are parsed from API code. All description fields are parsed from type declaration and struct type field comments. All path fields are parsed from a field’s JSON tag and merged with parent field path’s in dot-hierarchy notation.

x-descriptors

Check out the descriptor reference for available x-descriptors paths.

Examples

These examples assume Memcached, MemcachedSpec, and MemcachedStatus are the example projects’ kind, spec, and status.

  1. Set a displayName and resources for a customresourcedefinitions kind entry:

    1. //+operator-sdk:csv:customresourcedefinitions:displayName="Memcached App",resources={{Pod,v1,memcached-runner},{Deployment,v1,memcached-deployment}}
    2. type Memcached struct {
    3. metav1.TypeMeta `json:",inline"`
    4. metav1.ObjectMeta `json:"metadata,omitempty"`
    5. Spec MemcachedSpec `json:"spec,omitempty"`
    6. Status MemcachedStatus `json:"status,omitempty"`
    7. }

    ``

  2. Set displayName, path, xDescriptors, and description on a field for a customresourcedefinitions.specDescriptors entry:

    1. type MemcachedSpec struct {
    2. // Size is the size of the memcached deployment. <-- This will become Size's specDescriptors.description.
    3. //+operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Number of pods",xDescriptors={"urn:alm:descriptor:com.tectonic.ui:podCount","urn:alm:descriptor:io.kubernetes:custom"}
    4. Size int32 `json:"size"` // <-- Size's specDescriptors.path is inferred from this JSON tag.
    5. }

    ``

  3. Let the SDK infer all unmarked paths on a field for a customresourcedefinitions.specDescriptors entry:

    1. type MemcachedSpec struct {
    2. // Size is the size of the memcached deployment.
    3. //+operator-sdk:csv:customresourcedefinitions:type=spec
    4. Size int32 `json:"size"`
    5. }

    ``

    The SDK uses the Size fields’ json tag name as path, Size as displayName, and field comments as description.

  4. A comprehensive example:

    • Infer path, description, displayName, and x-descriptors for specDescriptors and statusDescriptors entries.
    • Create three resources entries each with kind, version, and name values.
    1. // Represents a cluster of Memcached apps
    2. //+operator-sdk:csv:customresourcedefinitions:displayName="Memcached App",resources={{Pod,v1,memcached-runner},{Deployment,v1,memcached-deployment}}
    3. type Memcached struct {
    4. metav1.TypeMeta `json:",inline"`
    5. metav1.ObjectMeta `json:"metadata,omitempty"`
    6. Spec MemcachedSpec `json:"spec,omitempty"`
    7. Status MemcachedStatus `json:"status,omitempty"`
    8. }
    9. type MemcachedSpec struct {
    10. Pods MemcachedPods `json:"pods"`
    11. }
    12. type MemcachedStatus struct {
    13. Pods MemcachedPods `json:"podStatuses"`
    14. //+operator-sdk:csv:customresourcedefinitions:type=status,displayName="Pod Count",xDescriptors="urn:alm:descriptor:com.tectonic.ui:podCount"
    15. PodCount int `json:"podCount"`
    16. }
    17. type MemcachedPods struct {
    18. // Size is the size of the memcached deployment.
    19. //+operator-sdk:csv:customresourcedefinitions:type=spec
    20. //+operator-sdk:csv:customresourcedefinitions.type=status
    21. Size int32 `json:"size"`
    22. }

    ``

    The generated customresourcedefinitions will look like:

    1. customresourcedefinitions:
    2. owned:
    3. - description: Represents a cluster of Memcached apps
    4. displayName: Memcached App
    5. kind: Memcached
    6. name: memcacheds.cache.example.com
    7. version: v1alpha1
    8. resources:
    9. - kind: Deployment
    10. name: memcached-deployment
    11. version: v1
    12. - kind: Pod
    13. name: memcached-runner
    14. version: v1
    15. specDescriptors:
    16. - description: The desired number of member Pods for the deployment.
    17. displayName: Size
    18. path: pods.size
    19. statusDescriptors:
    20. - description: The desired number of member Pods for the deployment.
    21. displayName: Size
    22. path: podStatuses.size
    23. - displayName: Size
    24. path: podCount
    25. x-descriptors:
    26. - 'urn:alm:descriptor:com.tectonic.ui:podCount'

    ``

Deprecated markers

Markers supported by operator-sdk prior to v1.0.0 are deprecated. You can migrate to the new marker system by running the following script:

  1. $ curl -sSLo migrate-markers.sh https://raw.githubusercontent.com/operator-framework/operator-sdk/master/hack/generate/migrate-markers.sh
  2. $ chmod +x ./migrate-markers.sh
  3. $ ./migrate-markers.sh path/to/*_types.go

Last modified February 11, 2021: align the sdk with kb (#4402) (4fc8a17c)