Getting Started > Kubernetes Operator API reference

Kubernetes Operator API reference

gremlin.com/v1alpha1

Agent

Agent is the Schema for the agents API. It describes a cluster's Gremlin installation. There is exactly one per cluster, named default.

Field	Type	Description
`apiVersion`	string	`gremlin.com/v1alpha1`
`kind`	string	`Agent`
`metadata`	ObjectMeta	Refer to the Kubernetes API documentation for the fields of `metadata`.
`spec`	AgentSpec

AgentSpec

AgentSpec defines the desired state of Agent.

Appears in: Agent

Field	Type	Description	Default
`credentialRef`	CredentialReference	credentialRef names the TeamCredential whose team owns this cluster in Gremlin.
`clusterId`	string	clusterId is the cluster's identifier in Gremlin. It identifies this installation, so it lives here and not on the TeamCredential, which can serve several clusters.
`agentVersion`	string	agentVersion is the exact agent image tag. Changing it rolls the agents, maxUnavailable at a time.
`image`	ImageSpec	image sets where the component images are pulled from.
`clientTags`	object (keys: string, values: string)	clientTags are tags the agents register with in Gremlin, as key-value pairs, for targeting them. They are passed to the agent as GREMLIN_CLIENT_TAGS. The agent drops a tag whose key or value is blank, and it splits the list on commas and each pair on the first =, so neither a key nor a value may contain a comma and a key may not contain =.
`network`	NetworkSpec	network is how every component reaches Gremlin. network.chao overrides it field by field.
`nodeSelector`	object (keys: string, values: string)	nodeSelector limits the agents to the nodes whose labels hold every pair. When omitted, an agent runs on every node it tolerates. It does not apply to Chao: set chao.nodeSelector for Chao.
`tolerations`	array of Toleration	tolerations let the agents run on tainted nodes. They do not apply to Chao: set chao.tolerations for Chao.
`maxUnavailable`	integer	maxUnavailable is how many agents can be down during a rollout. It is a number, not a percentage, and at least 1, because a DaemonSet rejects 0 when it cannot surge.	1
`chao`	ChaoSpec	chao configures Chao, Gremlin's Kubernetes-targeting component. Chao is enabled unless chao.enabled is false, and then chao.version is required, so set chao.version or set chao.enabled to false.
`securityContext`	SecurityContext	securityContext is the agent container's security context. Each field set here replaces the same field of the defaults (privileged false, allowPrivilegeEscalation false, readOnlyRootFilesystem false, and the nine capabilities the agent adds) as a whole. The API server checks the combination when the operator writes the DaemonSet, not when the Agent is applied.
`podSecurityContext`	PodSecurityContext	podSecurityContext is the agent pods' security context, taken as given. There is none by default. The API server checks it when the operator writes the DaemonSet, not when the Agent is applied.
`resources`	ResourceRequirements	resources are the requests and limits of the container, replacing the container's, which has none by default.
`affinity`	Affinity	affinity is the pods' scheduling affinity, taken as given. There is none by default.
`priorityClassName`	string	priorityClassName is the name of the PriorityClass of the pods. There is none by default.
`terminationGracePeriodSeconds`	integer	terminationGracePeriodSeconds is how long the pods have to stop. When omitted the API server's default of 30 applies.
`livenessProbe`	Probe	livenessProbe is the container's liveness probe. There is none by default.
`readinessProbe`	Probe	readinessProbe is the container's readiness probe. There is none by default.
`startupProbe`	Probe	startupProbe is the container's startup probe. There is none by default.
`lifecycle`	Lifecycle	lifecycle is the container's lifecycle hooks. There are none by default.
`dnsConfig`	PodDNSConfig	dnsConfig is the pods' DNS configuration, taken as given. There is none by default.
`hostAliases`	array of HostAlias	hostAliases are entries the kubelet adds to the pods' hosts file.
`envFrom`	array of EnvFromSource	envFrom are the sources the container takes environment variables from. A variable the operator sets, or one in extraEnv, wins over a source's. The contents of a source are not checked.
`updateStrategy`	DaemonSetUpdateStrategy	updateStrategy is how the DaemonSet rolls out a changed pod template: RollingUpdate, the default, or OnDelete, which replaces an agent pod only when it is deleted. A rollingUpdate block is refused: maxUnavailable at the root of spec is the agents' rollout budget, and it is not used with OnDelete.
`podLabels`	object (keys: string, values: string)	podLabels are labels added to the agent pod template, beside the operator's own. They are not on the DaemonSet itself or its selector. A key the operator sets is refused.
`podAnnotations`	object (keys: string, values: string)	podAnnotations are annotations added to the agent pod template, beside the operator's own. A key the operator sets is refused.
`initContainers`	array of Container	initContainers run before the agent container, after the operator's own, taken as given. None of the container settings of the agent container applies to them. The name gremlin is refused.
`extraEnv`	array of EnvVar	extraEnv are environment variables added to the agent container after the operator's own, so a value may use $(NAME) of one of them. A name the operator sets is refused.
`extraVolumes`	array of Volume	extraVolumes are volumes added to the agent pod after the operator's own, taken as given. A name the operator uses is refused, and so is a downwardAPI source with no items and no defaultMode, a projected source with no sources and no defaultMode, an ephemeral source with no volumeClaimTemplate, or an empty fc, flocker or storageos source. The admission rules read no other volume source, so the contents of a Secret or ConfigMap are not checked. An empty configMap, secret or image source, or an ephemeral claim template that holds nothing, is refused when the operator writes the pod.
`extraVolumeMounts`	array of VolumeMount	extraVolumeMounts are mounts added to the agent container after the operator's own. A mountPath must be absolute and canonical (no empty, . or .. segment) and at most 4096 bytes, and must not be or lie below a path the operator mounts.

AuthMode

Underlying type: string

AuthMode selects which kind of Gremlin credential the authRef Secret holds.

Appears in: AuthRef

Value	Description
`certificate`	AuthModeCertificate means the Secret holds a team certificate and key.
`secret`	AuthModeSecret means the Secret holds a team secret.

AuthRef

AuthRef points at the Secret that holds the team's identity for agents, Chao and the Failure Flags sidecar.

Appears in: TeamCredentialSpec

Field	Type	Description	Default
`secretName`	string	SecretName is the name of a Secret in the same namespace as the TeamCredential. It must be a valid DNS-1123 subdomain, which is what Kubernetes requires of Secret names.
`mode`	string (one of `certificate`, `secret`)	Mode selects the Secret's layout. In certificate mode the Secret holds the team certificate and its private key under either of two layouts, and the operator accepts both so a Secret created by the gremlin Helm chart (default name gremlin-team-cert) can be used unchanged: - tls.crt and tls.key, the layout cert-manager writes; or - gremlin.cert and gremlin.key, the layout the Helm chart writes. The private key must be a SEC1 "EC PRIVATE KEY"; PKCS#8 is rejected. In secret mode the Secret holds the team secret under the key teamSecret.	certificate

ChaoNetworkSpec

ChaoNetworkSpec is the Chao override of the cluster default network.

Appears in: NetworkSpec

Field	Type	Description
`serviceUrl`	string	serviceUrl is the Gremlin API URL, or a gateway standing in for it, for Chao. When omitted, Chao uses network.serviceUrl; the public default applies only when both are omitted. An explicit empty string is rejected.
`proxy`	ProxySpec	proxy is Chao's forward proxy. Without a url it only switches the default proxy on or off.
`tls`	TLSSpec	tls holds the trust bundle and the client identity.

ChaoSpec

ChaoSpec configures Chao.

Appears in: AgentSpec

Field	Type	Description	Default
`enabled`	boolean	enabled installs Chao. A Chao outage pauses Kubernetes targeting; node faults keep working.	true
`version`	string	version is the exact Chao image tag. Chao is versioned separately from the agent. It is required unless chao.enabled is false.
`namespaces`	array of string	namespaces limits Chao to these namespaces. Set at most one of namespaces and excludedNamespaces.
`excludedNamespaces`	array of string	excludedNamespaces keeps Chao out of these namespaces.
`replicas`	integer	replicas is how many Chao pods run. Chao 0.16 and later elects one to report to Gremlin; an older Chao registers each as the same client.	1
`securityContext`	SecurityContext	securityContext is Chao's container security context. Each field set here replaces the same field of the defaults (readOnlyRootFilesystem true, allowPrivilegeEscalation false, capabilities drop ALL) as a whole. The API server checks the combination when the operator writes the Deployment, not when the Agent is applied.
`podSecurityContext`	PodSecurityContext	podSecurityContext is Chao's pod security context, taken as given. There is none by default. The API server checks it when the operator writes the Deployment, not when the Agent is applied.
`resources`	ResourceRequirements	resources are the requests and limits of the container, replacing the container's, which has none by default.
`affinity`	Affinity	affinity is the pods' scheduling affinity, taken as given. There is none by default.
`priorityClassName`	string	priorityClassName is the name of the PriorityClass of the pods. There is none by default.
`terminationGracePeriodSeconds`	integer	terminationGracePeriodSeconds is how long the pods have to stop. When omitted the API server's default of 30 applies.
`livenessProbe`	Probe	livenessProbe is the container's liveness probe. There is none by default.
`readinessProbe`	Probe	readinessProbe is the container's readiness probe. There is none by default.
`startupProbe`	Probe	startupProbe is the container's startup probe. There is none by default.
`lifecycle`	Lifecycle	lifecycle is the container's lifecycle hooks. There are none by default.
`dnsConfig`	PodDNSConfig	dnsConfig is the pods' DNS configuration, taken as given. There is none by default.
`hostAliases`	array of HostAlias	hostAliases are entries the kubelet adds to the pods' hosts file.
`envFrom`	array of EnvFromSource	envFrom are the sources the container takes environment variables from. A variable the operator sets, or one in extraEnv, wins over a source's. The contents of a source are not checked.
`nodeSelector`	object (keys: string, values: string)	nodeSelector limits Chao to the nodes whose labels hold every pair. When omitted, Chao runs on any node.
`tolerations`	array of Toleration	tolerations let Chao run on tainted nodes.
`updateStrategy`	DeploymentStrategy	updateStrategy is how Chao's Deployment rolls out a changed pod template: RollingUpdate, the default, with the limits of rollingUpdate (25% and 25% when omitted), or Recreate, which stops the old pod before it starts the new one. A rollingUpdate block is refused beside Recreate.
`podLabels`	object (keys: string, values: string)	podLabels are labels added to the Chao pod template, beside the operator's own. They are not on the Deployment itself or its selector. A key the operator sets is refused.
`podAnnotations`	object (keys: string, values: string)	podAnnotations are annotations added to the Chao pod template, beside the operator's own. A key the operator sets is refused.
`initContainers`	array of Container	initContainers run before the Chao container, after the operator's own, taken as given. None of the container settings of the Chao container applies to them. The name chao is refused.
`extraEnv`	array of EnvVar	extraEnv are environment variables added to the Chao container after the operator's own, so a value may use $(NAME) of one of them. A name the operator sets is refused.
`extraVolumes`	array of Volume	extraVolumes are volumes added to the Chao pod after the operator's own, taken as given. A name the operator uses is refused, and so is a downwardAPI source with no items and no defaultMode, a projected source with no sources and no defaultMode, an ephemeral source with no volumeClaimTemplate, or an empty fc, flocker or storageos source. The admission rules read no other volume source, so the contents of a Secret or ConfigMap are not checked. An empty configMap, secret or image source, or an ephemeral claim template that holds nothing, is refused when the operator writes the pod.
`extraVolumeMounts`	array of VolumeMount	extraVolumeMounts are mounts added to the Chao container after the operator's own. A mountPath must be absolute and canonical (no empty, . or .. segment) and at most 4096 bytes, and must not be or lie below a path the operator mounts.

ClientTagValue

Underlying type: string

ClientTagValue is the value of a client tag.

Appears in: AgentSpec

CredentialReference

CredentialReference names a TeamCredential.

Appears in: AgentSpec

Field	Type	Description	Default
`name`	string	name is the TeamCredential name.
`namespace`	string	namespace is the TeamCredential's namespace.

ImageSpec

ImageSpec sets where component images are pulled from.

Appears in: AgentSpec

Field	Type	Description
`registry`	string	registry is the registry and repository prefix to pull from, for mirrors and Private Edition. When empty, images come from Gremlin's public registry.
`pullSecrets`	array of string	pullSecrets names image pull Secrets in the install namespace.
`pullPolicy`	string (one of `Always`, `Never`, `IfNotPresent`)	pullPolicy is the image pull policy of the agent and Chao containers, never of an init container. When omitted the API server chooses: Always for a latest or missing tag, and IfNotPresent otherwise.

KeyRef

KeyRef names a key in an object in the install namespace.

Appears in: TrustBundleSource

Field	Type	Description	Default
`name`	string	name is the object name.
`key`	string	key is the key that holds the PEM bundle.

NetworkSpec

NetworkSpec describes how a component reaches Gremlin. It is the cluster default on Agent.spec.network and carries the Chao override in chao, which is merged over the default (see MergeNetwork).

A setting is added here only once every component it applies to supports it.

Appears in: AgentSpec

Field	Type	Description
`serviceUrl`	string	serviceUrl is the Gremlin API URL, or a gateway standing in for it. When omitted, the operator uses https://api.gremlin.com/v1. An explicit empty string is rejected, because a blank value is almost always a templating mistake.
`proxy`	ProxySpec	proxy is a forward proxy for every connection to Gremlin.
`tls`	TLSSpec	tls holds the trust bundle and the client identity.
`chao`	ChaoNetworkSpec	chao overrides this network for Chao, field by field (see MergeNetwork).

PodSettings

PodSettings are the pod settings whose rules are the same for the agent DaemonSet and Chao's Deployment. The Agent inlines them at the root of spec for the agents and in spec.chao for Chao. Each value is the Kubernetes type of the field it sets, taken as given.

Appears in: AgentSpec ChaoSpec

Field	Type	Description
`resources`	ResourceRequirements	resources are the requests and limits of the container, replacing the container's, which has none by default.
`affinity`	Affinity	affinity is the pods' scheduling affinity, taken as given. There is none by default.
`priorityClassName`	string	priorityClassName is the name of the PriorityClass of the pods. There is none by default.
`terminationGracePeriodSeconds`	integer	terminationGracePeriodSeconds is how long the pods have to stop. When omitted the API server's default of 30 applies.
`livenessProbe`	Probe	livenessProbe is the container's liveness probe. There is none by default.
`readinessProbe`	Probe	readinessProbe is the container's readiness probe. There is none by default.
`startupProbe`	Probe	startupProbe is the container's startup probe. There is none by default.
`lifecycle`	Lifecycle	lifecycle is the container's lifecycle hooks. There are none by default.
`dnsConfig`	PodDNSConfig	dnsConfig is the pods' DNS configuration, taken as given. There is none by default.
`hostAliases`	array of HostAlias	hostAliases are entries the kubelet adds to the pods' hosts file.
`envFrom`	array of EnvFromSource	envFrom are the sources the container takes environment variables from. A variable the operator sets, or one in extraEnv, wins over a source's. The contents of a source are not checked.

ProxySpec

ProxySpec is a forward proxy.

Appears in: ChaoNetworkSpec NetworkSpec

Field	Type	Description
`enabled`	boolean	enabled switches the proxy off when false. Omitted counts as true, except in a network.chao proxy without a url, which keeps the default's setting.
`url`	string	url is the proxy URL. Only http:// and https:// are supported. Put credentials in credentialsSecret, never in the URL.
`credentialsSecret`	string	credentialsSecret names a Secret in the install namespace with the keys username and password, sent to the proxy as Basic auth.

SecretRef

SecretRef names a Secret in the TeamCredential's own namespace. There is no namespace field: a credential can only point at Secrets next to it.

Appears in: AuthRef

Field	Type	Description	Default
`secretName`	string	SecretName is the name of a Secret in the same namespace as the TeamCredential. It must be a valid DNS-1123 subdomain, which is what Kubernetes requires of Secret names.

TLSIdentity

TLSIdentity names the Secret that holds a client certificate and key.

Appears in: TLSSpec

Field	Type	Description	Default
`secretName`	string	secretName names a Secret in the install namespace with the keys tls.crt and tls.key.

TLSSpec

TLSSpec holds TLS settings shared by the connection to the proxy and to Gremlin.

Appears in: ChaoNetworkSpec NetworkSpec

Field	Type	Description	Default
`trustBundle`	TrustBundleSource	trustBundle is a CA bundle added to the built-in roots. It does not replace them.
`identity`	TLSIdentity	identity is the client certificate and key presented to a customer gateway or TLS proxy. It is a network credential, sent in addition to the team credential and never instead of it. One identity per component.

TeamCredential

TeamCredential is the Schema for the teamcredentials API.

Field	Type	Description
`apiVersion`	string	`gremlin.com/v1alpha1`
`kind`	string	`TeamCredential`
`metadata`	ObjectMeta	Refer to the Kubernetes API documentation for the fields of `metadata`.
`spec`	TeamCredentialSpec

TeamCredentialSpec

TeamCredentialSpec defines the desired state of TeamCredential.

Appears in: TeamCredential

Field	Type	Description	Default
`teamId`	string	TeamID is the Gremlin team this credential acts for, 1 to 128 characters. It cannot be changed after creation.
`authRef`	AuthRef	AuthRef points at the Secret holding the team's certificate (or team secret).

TrustBundleSource

TrustBundleSource points at a PEM CA bundle in a ConfigMap or a Secret in the install namespace. Exactly one of configMapRef and secretRef is set.

Appears in: TLSSpec

Field	Type	Description	Default
`configMapRef`	KeyRef	configMapRef names a ConfigMap in the install namespace and the key in it.
`secretRef`	KeyRef	secretRef names a Secret in the install namespace and the key in it.