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:

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

   ``

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

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

   ``

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

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

   ``

   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.

   // Represents a cluster of Memcached apps
   // +operator-sdk:csv:customresourcedefinitions:displayName="Memcached App",resources={{Pod,v1,memcached-runner},{Deployment,v1,memcached-deployment}}
   type Memcached struct {
       metav1.TypeMeta   `json:",inline"`
       metav1.ObjectMeta `json:"metadata,omitempty"`
       Spec   MemcachedSpec   `json:"spec,omitempty"`
       Status MemcachedStatus `json:"status,omitempty"`
   }
   type MemcachedSpec struct {
       Pods MemcachedPods `json:"pods"`
   }
   type MemcachedStatus struct {
       Pods          MemcachedPods `json:"podStatuses"`
       // +operator-sdk:csv:customresourcedefinitions:type=status,displayName="Pod Count",xDescriptors="urn:alm:descriptor:com.tectonic.ui:podCount"
       PodCount int                      `json:"podCount"`
   }
   type MemcachedPods struct {
       // Size is the size of the memcached deployment.
       // +operator-sdk:csv:customresourcedefinitions:type=spec
       // +operator-sdk:csv:customresourcedefinitions.type=status
       Size int32 `json:"size"`
   }

   ``

   The generated customresourcedefinitions will look like:

   customresourcedefinitions:
     owned:
     - description: Represents a cluster of Memcached apps
       displayName: Memcached App
       kind: Memcached
       name: memcacheds.cache.example.com
       version: v1alpha1
       resources:
       - kind: Deployment
         name: memcached-deployment
         version: v1
       - kind: Pod
         name: memcached-runner
         version: v1
       specDescriptors:
       - description: The desired number of member Pods for the deployment.
         displayName: Size
         path: pods.size
       statusDescriptors:
       - description: The desired number of member Pods for the deployment.
         displayName: Size
         path: podStatuses.size
       - displayName: Size
         path: podCount
         x-descriptors:
         - '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:

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

Last modified August 18, 2020: docs: fix Go API xDesriptor marker example (#3750) (ddce5985)