04 Spec

Using the declarative approach, a spec is the reign of the user, where he/she declares what is needed.

To understand better what Spec actually shoud keep, lets look at the most common resource in kubernetes, the Pod:

PodSpec

Back to looking over our Pod example:

// PodSpec is a description of a pod.
type PodSpec struct {
	Volumes                       []Volume                   `json:"volumes,omitempty"`
	InitContainers                []Container                `json:"initContainers,omitempty"`
	Containers                    []Container                `json:"containers"`
	EphemeralContainers           []EphemeralContainer       `json:"ephemeralContainers,omitempty"`
	RestartPolicy                 RestartPolicy              `json:"restartPolicy,omitempty"`
	TerminationGracePeriodSeconds *int64                     `json:"terminationGracePeriodSeconds,omitempty"`
	ActiveDeadlineSeconds         *int64                     `json:"activeDeadlineSeconds,omitempty"`
	DNSPolicy                     DNSPolicy                  `json:"dnsPolicy,omitempty"`
	NodeSelector                  map[string]string          `json:"nodeSelector,omitempty"`
	ServiceAccountName            string                     `json:"serviceAccountName,omitempty"`
	AutomountServiceAccountToken  *bool                      `json:"automountServiceAccountToken,omitempty"`
	NodeName                      string                     `json:"nodeName,omitempty"`
	HostNetwork                   bool                       `json:"hostNetwork,omitempty"`
	HostPID                       bool                       `json:"hostPID,omitempty"`
	HostIPC                       bool                       `json:"hostIPC,omitempty"`
	ShareProcessNamespace         *bool                      `json:"shareProcessNamespace,omitempty"`
	SecurityContext               *PodSecurityContext        `json:"securityContext,omitempty"`
	ImagePullSecrets              []LocalObjectReference     `json:"imagePullSecrets,omitempty"`
	Hostname                      string                     `json:"hostname,omitempty"`
	Subdomain                     string                     `json:"subdomain,omitempty"`
	Affinity                      *Affinity                  `json:"affinity,omitempty"`
	SchedulerName                 string                     `json:"schedulerName,omitempty"`
	Tolerations                   []Toleration               `json:"tolerations,omitempty"`
	HostAliases                   []HostAlias                `json:"hostAliases,omitempty"`
	PriorityClassName             string                     `json:"priorityClassName,omitempty"`
	Priority                      *int32                     `json:"priority,omitempty"`
	DNSConfig                     *PodDNSConfig              `json:"dnsConfig,omitempty"`
	ReadinessGates                []PodReadinessGate         `json:"readinessGates,omitempty"`
	RuntimeClassName              *string                    `json:"runtimeClassName,omitempty"`
	EnableServiceLinks            *bool                      `json:"enableServiceLinks,omitempty"`
	PreemptionPolicy              *PreemptionPolicy          `json:"preemptionPolicy,omitempty"`
	Overhead                      ResourceList               `json:"overhead,omitempty"`
	TopologySpreadConstraints     []TopologySpreadConstraint `json:"topologySpreadConstraints,omitempty"`
}

A few important things are noted:

• No status or process related data: Remeber it should Declare its desired state
• Pointers to simplify maintainance of yaml files

Container

Volume

Note: A few properties or comments were removed to simply reading

Original Source

// Volume represents a named volume in a pod that may be accessed by any container in the pod.
type Volume struct {
	// Volume's name.
	// Must be a DNS_LABEL and unique within the pod.
	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
	// VolumeSource represents the location and type of the mounted volume.
	// If not specified, the Volume is implied to be an EmptyDir.
	// This implied behavior is deprecated and will be removed in a future version.
	VolumeSource `json:",inline" protobuf:"bytes,2,opt,name=volumeSource"`
}

// Represents the source of a volume to mount.
// Only one of its members may be specified.
type VolumeSource struct {
	// HostPath represents a pre-existing file or directory on the host
	// machine that is directly exposed to the container. This is generally
	// used for system agents or other privileged things that are allowed
	// to see the host machine. Most containers will NOT need this.
	// More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
	// ---
	// TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not
	// mount host directories as read/write.
	// +optional
	HostPath *HostPathVolumeSource `json:"hostPath,omitempty" protobuf:"bytes,1,opt,name=hostPath"`
	// EmptyDir represents a temporary directory that shares a pod's lifetime.
	// More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
	// +optional
	EmptyDir *EmptyDirVolumeSource `json:"emptyDir,omitempty" protobuf:"bytes,2,opt,name=emptyDir"`
	// Secret represents a secret that should populate this volume.
	// More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
	// +optional
	Secret *SecretVolumeSource `json:"secret,omitempty" protobuf:"bytes,6,opt,name=secret"`
	// PersistentVolumeClaimVolumeSource represents a reference to a
	// PersistentVolumeClaim in the same namespace.
	// More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
	// +optional
	PersistentVolumeClaim *PersistentVolumeClaimVolumeSource `json:"persistentVolumeClaim,omitempty" protobuf:"bytes,10,opt,name=persistentVolumeClaim"`
	
	// ConfigMap represents a configMap that should populate this volume
	// +optional
	ConfigMap *ConfigMapVolumeSource `json:"configMap,omitempty" protobuf:"bytes,19,opt,name=configMap"`
}

The VolumeSource follows the general guidelines and simplify the way to implement different flavors of a Volume:

[...]
   volumes:
   - name: abc
     configMap: # configmap data
       name: configmap
   - name: bcd
     secret: # secret data
        name: secret

Summary

• Keep declarations easy to understand and maintain
• Reuse properties specifications whenever possible. This also means that specifications should be slightly more generic, at the same time provide space to expand in the future
• Avoid populating properties that were not defined by the user