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.

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.

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 July 22, 2020: generate: parse CSV annotations with `controller-tools/pkg/markers` (#2792) (5256f82d)