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.
-
Set a
displayName
andresources
for acustomresourcedefinitions
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"` }
``
-
Set
displayName
,path
,xDescriptors
, anddescription
on a field for acustomresourcedefinitions.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. }
``
-
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 aspath
,Size
asdisplayName
, and field comments asdescription
. -
A comprehensive example:
- Infer
path
,description
,displayName
, andx-descriptors
forspecDescriptors
andstatusDescriptors
entries. - Create three
resources
entries each withkind
,version
, andname
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'
``
- Infer
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