API.md

Packages:

• crds.wizardofoz.co/v1alpha1

crds.wizardofoz.co/v1alpha1

Package v1alpha1 contains API Schema definitions for the templates v1alpha1 API group

Resource Types:

AccessConfig

(Appears on:ExecAccessTemplateSpec, PodAccessTemplateSpec)

AccessConfig provides a common interface for our Template structs (which implement ITemplateResource) for defining which entities are being granted access to a resource, and for how long they are granted that access.

Field	Description
allowedGroups []string	AllowedGroups lists out the groups (in string name form) that will be allowed to Exec into the target pod.
defaultDuration string	DefaultDuration sets the default time that an access request resource will live. Must be set below MaxDuration. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
maxDuration string	MaxDuration sets the maximum duration that an access request resource can request to stick around. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
accessCommand string	AccessCommand is used to describe to the user how they can make use of their temporary access. The AccessCommand can reference data from a Pod ObjectMeta.

ControllerKind (string alias)

(Appears on:CrossVersionObjectReference)

ControllerKind is a string that represents an Apps/V1 known controller kind that this codebase supports. This is used to limit the inputs on the AccessTemplate and ExecAccessTemplate CRDs.

Value	Description
"DaemonSet"	DaemonSetController maps to APIVersion: apps/v1, Kind: DaemonSet
"Deployment"	DeploymentController maps to APIVersion: apps/v1, Kind: Deployment
"StatefulSet"	StatefulSetController maps to APIVersion: apps/v1, Kind: StatfulSet

CoreStatus

(Appears on:ExecAccessRequestStatus, ExecAccessTemplateStatus, PodAccessRequestStatus, PodAccessTemplateStatus)

CoreStatus provides a common set of .Status fields and functions. The goal is to conform to the interfaces.OzResource interface commonly across all of our core CRDs.

Field	Description
conditions []Kubernetes meta/v1.Condition	Current status of the Access Template
ready bool	Simple boolean to let us know if the resource is ready for use or not
accessMessage string	AccessMessage is used to describe to the user how they can make use of their temporary access request. Eg, for a PodAccessTemplate the value set here would be something like: “Access Granted, connect to your pod with: kubectl exec -ti -n namespace pod-xyz – /bin/bash”

CrossVersionObjectReference

(Appears on:ExecAccessTemplateSpec, PodAccessTemplateSpec)

CrossVersionObjectReference provides us a generic way to define a reference to an APIGroup, Kind and Name of a particular resource. Primarily used for the AccessTemplate and ExecAccessTemplate, but generic enough to be used in other resources down the road.

Field	Description
apiVersion string	Defines the “APIVersion” of the resource being referred to. Eg, “apps/v1”. TODO: Figure out how to regex validate that it has a “/” in it
kind ControllerKind	Defines the “Kind” of resource being referred to.
name string	Defines the “metadata.Name” of the target resource.

ExecAccessRequest

ExecAccessRequest is the Schema for the execaccessrequests API

Field	Description
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ExecAccessRequestSpec	templateName string Defines the name of the ExecAcessTemplate that should be used to grant access to the target resource. targetPod string TargetPod is used to explicitly define the target pod that the Exec privilges should be granted to. If not supplied, then a random pod is chosen. duration string Duration sets the length of time from the spec.creationTimestamp that this object will live. After the time has expired, the resouce will be automatically deleted on the next reconcilliation loop. If omitted, the spec.defautlDuration from the ExecAccessTemplate is used. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
status ExecAccessRequestStatus

ExecAccessRequestSpec

(Appears on:ExecAccessRequest)

ExecAccessRequestSpec defines the desired state of ExecAccessRequest

Field	Description
templateName string	Defines the name of the ExecAcessTemplate that should be used to grant access to the target resource.
targetPod string	TargetPod is used to explicitly define the target pod that the Exec privilges should be granted to. If not supplied, then a random pod is chosen.
duration string	Duration sets the length of time from the spec.creationTimestamp that this object will live. After the time has expired, the resouce will be automatically deleted on the next reconcilliation loop. If omitted, the spec.defautlDuration from the ExecAccessTemplate is used. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

ExecAccessRequestStatus

(Appears on:ExecAccessRequest)

ExecAccessRequestStatus defines the observed state of ExecAccessRequest

Field	Description
CoreStatus CoreStatus	(Members of CoreStatus are embedded into this type.)
podName string	The Target Pod Name where access has been granted

ExecAccessTemplate

ExecAccessTemplate is the Schema for the execaccesstemplates API

Field	Description
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ExecAccessTemplateSpec	accessConfig AccessConfig AccessConfig provides a common struct for defining who has access to the resources this template controls, how long they have access, etc. controllerTargetRef CrossVersionObjectReference ControllerTargetRef provides a pattern for referencing objects from another API in a generic way.
status ExecAccessTemplateStatus

ExecAccessTemplateSpec

(Appears on:ExecAccessTemplate)

ExecAccessTemplateSpec defines the desired state of ExecAccessTemplate

Field	Description
accessConfig AccessConfig	AccessConfig provides a common struct for defining who has access to the resources this template controls, how long they have access, etc.
controllerTargetRef CrossVersionObjectReference	ControllerTargetRef provides a pattern for referencing objects from another API in a generic way.

ExecAccessTemplateStatus

(Appears on:ExecAccessTemplate)

ExecAccessTemplateStatus is the core set of status fields that we expect to be in each and every one of our template (AccessTemplate, ExecAccessTemplate, etc) resources.

Field	Description
CoreStatus CoreStatus	(Members of CoreStatus are embedded into this type.)

IConditionType

IConditionType provides an interface for accepting any condition string that has a String() function. This simplifies the controllers/internal/status/update_status.go code to have a single UpdateStatus() function.

ICoreResource

The ICoreResource interface wraps a standard client.Object resource (metav1.Object + runtime.Object) with a few additional requirements for common methods that we use throughout our reconciliation process.

ICoreStatus

ICoreStatus is used to define the core common status functions that all Status structs in this API must adhere to. These common functions simplify the reconciler() functions so that they can easily get/set status on the resources in a common way.

IPodRequestResource

IPodRequestResource is a Pod-access specific request interface that exposes a few more functions for storing references to specific Pods that the requestor is being granted access to.

IRequestResource

IRequestResource represents a common “AccesRequest” resource for the Oz Controller. These requests have a common set of required methods that are used by the OzRequestReconciler.

IRequestStatus

IRequestStatus is a more specific Status interface that enables getting and setting access instruction methods.

ITemplateResource

ITemplateResource represents a common “AccessTemplate” resource for the Oz Controller. These templates provide different types of access into resources (eg, “Exec” vs “Debug” vs “launch me a dedicated pod”). A set of common methods are required though that are used by the OzTemplateReconciler.

ITemplateStatus

ITemplateStatus provides a more specific Status interface for Access Templates. Functionality to come in the future.

JSONPatchOperation

(Appears on:PodTemplateSpecMutationConfig)

JSONPatchOperation represents a JSON Patch operation defined in https://www.rfc-editor.org/rfc/rfc6902.html

Field	Description
op JSONPatchOperationType
path string
value k8s.io/apimachinery/pkg/util/intstr.IntOrString

JSONPatchOperationType (string alias)

(Appears on:JSONPatchOperation)

JSONPatchOperationType represents a JSON Patch operation defined in https://www.rfc-editor.org/rfc/rfc6902.html. Eg, “add”, “remove”, etc.

Value	Description
"add"
"copy"
"move"
"remove"
"replace"
"test"

PodAccessRequest

PodAccessRequest is the Schema for the accessrequests API

Field	Description
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec PodAccessRequestSpec	templateName string Defines the name of the ExecAcessTemplate that should be used to grant access to the target resource. duration string Duration sets the length of time from the spec.creationTimestamp that this object will live. After the time has expired, the resouce will be automatically deleted on the next reconcilliation loop. If omitted, the spec.defautlDuration from the ExecAccessTemplate is used. Valid time units are “s”, “m”, “h”.
status PodAccessRequestStatus

PodAccessRequestSpec

(Appears on:PodAccessRequest)

PodAccessRequestSpec defines the desired state of AccessRequest

Field	Description
templateName string	Defines the name of the ExecAcessTemplate that should be used to grant access to the target resource.
duration string	Duration sets the length of time from the spec.creationTimestamp that this object will live. After the time has expired, the resouce will be automatically deleted on the next reconcilliation loop. If omitted, the spec.defautlDuration from the ExecAccessTemplate is used. Valid time units are “s”, “m”, “h”.

PodAccessRequestStatus

(Appears on:PodAccessRequest)

PodAccessRequestStatus defines the observed state of AccessRequest

Field	Description
CoreStatus CoreStatus	(Members of CoreStatus are embedded into this type.)
podName string	The Target Pod Name where access has been granted

PodAccessTemplate

PodAccessTemplate is the Schema for the accesstemplates API

Field	Description
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec PodAccessTemplateSpec	accessConfig AccessConfig AccessConfig provides a common struct for defining who has access to the resources this template controls, how long they have access, etc. controllerTargetRef CrossVersionObjectReference ControllerTargetRef provides a pattern for referencing objects from another API in a generic way. controllerTargetMutationConfig PodTemplateSpecMutationConfig ControllerTargetMutationConfig contains parameters that allow for customizing the copy of a controller-sourced PodSpec. This setting is only valid if controllerTargetRef is set. podSpec Kubernetes core/v1.PodSpec PodSpec … maxStorage k8s.io/apimachinery/pkg/api/resource.Quantity Upper bound of the ephemeral storage that an AccessRequest can make against this template for the primary container. maxCpu k8s.io/apimachinery/pkg/api/resource.Quantity Upper bound of the CPU that an AccessRequest can make against this tmemplate for the primary container. maxMemory k8s.io/apimachinery/pkg/api/resource.Quantity Upper bound of the memory that an AccessRequest can make against this template for the primary container.
status PodAccessTemplateStatus

PodAccessTemplateSpec

(Appears on:PodAccessTemplate)

PodAccessTemplateSpec defines the desired state of AccessTemplate

Field	Description
accessConfig AccessConfig	AccessConfig provides a common struct for defining who has access to the resources this template controls, how long they have access, etc.
controllerTargetRef CrossVersionObjectReference	ControllerTargetRef provides a pattern for referencing objects from another API in a generic way.
controllerTargetMutationConfig PodTemplateSpecMutationConfig	ControllerTargetMutationConfig contains parameters that allow for customizing the copy of a controller-sourced PodSpec. This setting is only valid if controllerTargetRef is set.
podSpec Kubernetes core/v1.PodSpec	PodSpec …
maxStorage k8s.io/apimachinery/pkg/api/resource.Quantity	Upper bound of the ephemeral storage that an AccessRequest can make against this template for the primary container.
maxCpu k8s.io/apimachinery/pkg/api/resource.Quantity	Upper bound of the CPU that an AccessRequest can make against this tmemplate for the primary container.
maxMemory k8s.io/apimachinery/pkg/api/resource.Quantity	Upper bound of the memory that an AccessRequest can make against this template for the primary container.

PodAccessTemplateStatus

(Appears on:PodAccessTemplate)

PodAccessTemplateStatus defines the observed state of PodAccessTemplate

Field	Description
CoreStatus CoreStatus	(Members of CoreStatus are embedded into this type.)

PodTemplateSpecMutationConfig

(Appears on:PodAccessTemplateSpec)

PodTemplateSpecMutationConfig provides a common pattern for describing mutations to an existing PodSpec that should be applied. The primary use case is in the PodAccessTemplate, where an existing controller (Deployment, DaemonSet, StatefulSet) can be used as the reference for the PodSpec that is launched for the user. However, the operator may want to make modifications to the PodSpec at launch time (eg, change the entrypoint command or arguments).

TODO: Add affinity

Field	Description
defaultContainerName string	DefaultContainerName allows the operator to define which container is considered the default container, and that is the container that this mutation configuration applies to. If not set, then the first container defined in the spec.containers[] list is patched.
command string	Command is used to override the .Spec.containers[0].command field for the target Pod and Container. This can be handy in ensuring that the default application does not start up and do any work. If set, this overrides the Spec.conatiners[0].args property as well.
args string	Args will override the Spec.containers[0].args property.
env []Kubernetes core/v1.EnvVar	Env allows overriding specific environment variables (or adding new ones). Note, we do not purge the original environmnt variables.
resources Kubernetes core/v1.ResourceRequirements	If supplied these resource requirements will override the default .Spec.containers[0].resource requested for the the pod. Note though that we do not override all of the resource requests in the Pod because there may be many containers.
podAnnotations string	If supplied, these annotations are applied to the target PodTemplateSpec. These are merged into the final Annotations. If you want to replace the annotations, make sure to set the purgeAnnotations flag to true.
podLabels string	If supplied, Oz will insert these labels into the target PodTemplateSpec. By default Oz purges all Labels from pods (to prevent the new Pod from having traffic routed to it), so this is effectively a new set of labels applied to the Pod.
purgeAnnotations bool	By default, Oz keeps the original PodTemplateSpec metadata.annotations field. If you want to purge this, set this flag to true.
patchSpecOperations []JSONPatchOperation	PatchSpecOperations contains a list of JSON patch operations to apply to the PodSpec. JSONPatch
keepTerminationGracePeriod bool	By default, Oz wipes out the PodSpec terminationGracePeriodSeconds setting on Pods to ensure that they can be killed as soon as the AccessRequest expires. This flag overrides that behavior.
keepLivenessProbe bool	By default, Oz wipes out the PodSpec livenessProbe configuration for the default container so that the container does not get terminated if the main application is not running or passing checks. This setting overrides that behavior.
keepReadinessProbe bool	By default, Oz wipes out the PodSpec readinessProbe configuration for the default container so that the container does not get terminated if the main application is not running or passing checks. This setting overrides that behavior.
keepStartupProbe bool	By default, Oz wipes out the PodSpec startupProbe configuration for the default container so that the container does not get terminated if the main application is not running or passing checks. This setting overrides that behavior.
keepTopologySpreadConstraints bool	By default, Oz wipes out the PodSpec topologySpreadConstraints configuration for the Pod because these access pods are not part of the same group of pods that are passing traffic. This setting overrides that behavior.
nodeSelector string	If supplied, Oz will insert these nodeSelector into the target PodTemplateSpec.

RequestConditionTypes (string alias)

RequestConditionTypes defines a set of known Status.Condition[].ConditionType fields that are used throughout the AccessRequest and AccessTemplate reconcilers.

Value	Description
"AccessMessage"	ConditionAccessMessage is used to record
"AccessResourcesCreated"	ConditionAccessResourcesCreated indicates whether or not the target access request resources have been properly created.
"AccessResourcesReady"	ConditionAccessResourcesReady indicates that all of the “access resources” (eg, a Pod) are up and in the ready state.
"AccessStillValid"	ConditionAccessStillValid is continaully updated based on whether or not the Access Request has timed out.
"AccessDurationsValid"	ConditionRequestDurationsValid is used by both AccessTemplate and AccessRequest resources. It indicates whether or not the various duration fields are valid.
"TargetTemplateExists"	ConditionTargetTemplateExists indicates that the Access Request is pointing to a valid Access Template.

TemplateConditionTypes (string alias)

TemplateConditionTypes defines a set of known Status.Condition[].ConditionType fields that are used throughout the AccessTemplate reconcilers and written to the ITemplateResource resources.

Value	Description
"TargetRefExists"	ConditionTargetRefExists indicates whether or not an AccessTemplate is pointing to a valid Controller.
"TemplateDurationsValid"	ConditionTemplateDurationsValid is used by both AccessTemplate and AccessRequest resources. It indicates whether or not the various duration fields are valid.

---

Generated with gen-crd-api-reference-docs .