Documentation
¶
Overview ¶
Package caas provides abstractions for container orchestration platforms.
These abstractions enable Juju to deploy and manage applications on Kubernetes and other container platforms (providing application lifecycle operations, storage management, networking configuration, model operator deployment, etc.). Applications are deployed with configurable deployment types (stateless, stateful, daemon) and service types (cluster, load balancer, external, etc.).
See github.com/juju/juju/environs for the base environment provider interface. See github.com/juju/juju/internal/provider/kubernetes for the Kubernetes implementation. See github.com/juju/juju/internal/worker/caasapplicationprovisioner for application provisioning using brokers.
Index ¶
- Constants
- Variables
- func RegisterContainerProvider(name string, p ContainerEnvironProvider, alias ...string) (unregister func())
- type Application
- type ApplicationBroker
- type ApplicationConfig
- type ApplicationState
- type Broker
- type CharmStorageParams
- type ClusterVersionGetter
- type ContainerConfig
- type ContainerEnvironProvider
- type CredentialChecker
- type DeploymentMode
- type DeploymentParams
- type DeploymentState
- type DeploymentType
- type FilesystemInfo
- type ModelOperatorConfig
- type ModelOperatorManager
- type MountConfig
- type NewContainerBrokerFunc
- type Operator
- type OperatorConfig
- type ProxyManager
- type RunAs
- type Service
- type ServiceInterface
- type ServiceManager
- type ServiceParam
- type ServiceParams
- type ServicePort
- type ServiceType
- type StatusCallbackFunc
- type StorageValidator
- type Unit
- type Upgrader
- type VolumeInfo
Constants ¶
const ServiceNotFound = errors.ConstError("application service not found")
ServiceNotFound indicates that the application's address Service is absent. It distinguishes Service deletion from a missing workload or status resource.
Variables ¶
var ( // ModelOperatorStartUpSh is the start script for CAAS model operator pods. // It detects whether the image provides the current jujuagentd binary or // only the legacy jujud binary (pre-rename), and invokes whichever is // present. This allows a controller that has been upgraded to continue // managing model operators whose pods are still running an older image // (i.e. models that have not yet been upgraded). Once the model is // upgraded the pod image is refreshed and jujuagentd is used directly. // // Format args: // %[1]s - JUJU_DATA_DIR (e.g. /var/lib/juju) // %[2]s - tools subdirectory name (always "tools") // %[3]s - exec command using jujuagentd (new images) // %[4]s - exec command using jujud (old images) ModelOperatorStartUpSh = ` export JUJU_DATA_DIR=%[1]s export JUJU_TOOLS_DIR=$JUJU_DATA_DIR/%[2]s mkdir -p $JUJU_TOOLS_DIR if [ -x /opt/jujuagentd ]; then cp /opt/jujuagentd $JUJU_TOOLS_DIR/jujuagentd %[3]s else cp /opt/jujud $JUJU_TOOLS_DIR/jujud %[4]s fi `[1:] // APIServerStartUpSh is the start script for the "api-server" container // in the controller pod (Pebble running jujud and jujuagentd). APIServerStartUpSh = ` export JUJU_DATA_DIR=%[1]s export JUJU_TOOLS_DIR=$JUJU_DATA_DIR/tools export JUJU_CONTROLLER_DIR=%[1]s/controller export JUJU_BOOTSTRAP_PARAMS_PATH=%[1]s/bootstrap-params mkdir -p $JUJU_TOOLS_DIR cp /opt/jujud $JUJU_TOOLS_DIR/jujud cp /opt/jujuagentd $JUJU_TOOLS_DIR/jujuagentd %[2]s mkdir -p /var/lib/pebble/default/layers cat > /var/lib/pebble/default/layers/001-controller.yaml <<'EOF' %[3]s EOF exec /opt/pebble run --http :%[4]s --verbose `[1:] )
Functions ¶
func RegisterContainerProvider ¶
func RegisterContainerProvider(name string, p ContainerEnvironProvider, alias ...string) (unregister func())
RegisterContainerProvider is used for providers that we want to use for managing 'instances', but are not possible sources for 'juju bootstrap'.
Types ¶
type Application ¶
type Application interface {
Ensure(config ApplicationConfig) error
Exists() (DeploymentState, error)
Delete() error
Watch(context.Context) (watcher.NotifyWatcher, error)
WatchReplicas() (watcher.NotifyWatcher, error)
// ApplicationPodSpec returns the pod spec needed to run the application workload.
ApplicationPodSpec(config ApplicationConfig) (*core.PodSpec, error)
// Scale reconciles the application's replica count. Scale must be >= 0.
// The operation stops if ctx is cancelled.
Scale(context.Context, int) error
// ScaleRange reconciles a StatefulSet to a contiguous ordinal range. The
// replicaCount and startOrdinal define the half-open range
// [startOrdinal, startOrdinal+replicaCount). Sparse ordinal ranges are not
// supported. Both values must be non-negative.
// The operation stops if ctx is cancelled.
ScaleRange(ctx context.Context, replicaCount, startOrdinal int) error
// Trust sets up the role on the application's service account to
// give full access to the cluster.
Trust(bool) error
State() (ApplicationState, error)
// Units of the application fetched from kubernetes by matching pod labels.
Units() ([]Unit, error)
UnitsToRemove(context.Context, int) ([]string, error)
// Service returns the service associated with the application.
// ServiceNotFound indicates that its address Service no longer exists.
Service() (*Service, error)
// EnsurePVCs ensures that Persistent Volume Claims (PVCs) are created for the given
// filesystems, unit attachments, and storage unique ID. It creates PVCs
// based on the provided filesystem parameters and handles volume
// attachments for StatefulSet applications. Returns a cleanup function
// that can be used to delete the created PVCs if rollback is needed,
// and any error encountered during the process.
EnsurePVCs(
[]storage.KubernetesFilesystemParams,
map[string][]storage.KubernetesFilesystemUnitAttachmentParams,
string,
) error
// EnsureControllerNonce reconciles a nonce entry for the given controller
// ordinal into the controller ConfigMap. This is called before scaling the
// controller StatefulSet so new pods can validate their nonce against the
// database. For non-controller applications this is a no-op.
EnsureControllerNonce(ctx context.Context, ordinal int, nonce string) error
ServiceInterface
}
Application is for interacting with the CAAS substrate.
type ApplicationBroker ¶
type ApplicationBroker interface {
// Application returns the broker interface for an Application
Application(string, DeploymentType) Application
// Units returns all units and any associated filesystems
// of the specified application. Filesystems are mounted
// via volumes bound to the unit.
Units(ctx context.Context, appName string) ([]Unit, error)
// AnnotateUnit annotates the specified pod (name or uid) with a unit tag.
AnnotateUnit(ctx context.Context, appName string, podName string, unit names.UnitTag) error
}
ApplicationBroker provides an API for accessing the broker interface for individual applications and watching their units.
type ApplicationConfig ¶
type ApplicationConfig struct {
// Controller indicates this application hosts the Juju controller.
Controller bool
// AgentVersion is the Juju version of the agent image.
AgentVersion semversion.Number
// AgentImagePath is the docker registry URL for the charm container.
AgentImagePath string
// CharmBaseImagePath is the docker registry URL for the workload containers to run pebble.
CharmBaseImagePath string
// IsPrivateImageRepo indicates if the images repositories are private or not.
// If they are, we need to set the image pull secret.
IsPrivateImageRepo bool
// CharmModifiedVersion is a monotonically incrementing version number
// that represents the version of the charm and resources with regards to
// this application. The CAAS provider will pass this to the uniter worker
// to ensure the container infrastructure matches the charm.
CharmModifiedVersion int
// Containers is the list of containers that make up the container (excluding uniter and init containers).
Containers map[string]ContainerConfig
// ExistingContainers is a list of names for containers which will be added
// to the application pod spec outside the ApplicationPodSpec method.
// These containers will be added to the JUJU_CONTAINER_NAMES env variable
// in the charm container, but we will not create new container specs for
// them, as they are assumed to already exist.
ExistingContainers []string
// IntroductionSecret
IntroductionSecret string
// ControllerAddresses is a comma separated list of controller addresses.
// TODO: Use model-operator service instead for introduction, so controller addresses can change
// without having to update deployed application.
ControllerAddresses string
// ControllerCertBundle is a PEM cert bundle for talking to the Juju controller.
ControllerCertBundle string
// ResourceTags is a set of tags to set on the operator pod.
ResourceTags map[string]string
// Constraints is a set of constraints on
// the workload containers.
Constraints constraints.Value
// Filesystems is a set of parameters for filesystems that should be created.
Filesystems []storage.KubernetesFilesystemParams
// Devices is a set of parameters for Devices that is required.
Devices []devices.KubernetesDeviceParams
// Trust is set to true to give the application cloud access.
Trust bool
// InitialScale is used to provide the initial desired scale of the application.
// After the application is created, InitialScale has no effect.
InitialScale int
// CharmUser controls what user the charm/unit agent runs as.
CharmUser RunAs
// StorageUniqueID is used to construct the PVC name for an application.
StorageUniqueID string
}
ApplicationConfig is the config passed to the application units.
type ApplicationState ¶
ApplicationState represents the application state.
type Broker ¶
type Broker interface {
// Provider returns the ContainerEnvironProvider that created this Broker.
Provider() ContainerEnvironProvider
// InstancePrechecker provides a means of "prechecking" placement
// arguments before recording them in state.
environs.InstancePrechecker
// BootstrapEnviron defines methods for bootstrapping a controller.
environs.BootstrapEnviron
// ResourceAdopter defines methods for adopting resources.
environs.ResourceAdopter
// Networking is an interface providing networking-related operations
// for an CAAS Environ.
environs.Networking
// StorageValidator provides methods to validate storage.
StorageValidator
// Upgrader provides the API to perform upgrades.
Upgrader
// APIVersion returns the version of the container orchestration layer.
APIVersion() (string, error)
// GetSecretToken returns the token content for the specified secret name.
GetSecretToken(ctx context.Context, name string) (string, error)
// ClusterVersionGetter provides methods to get cluster version information.
ClusterVersionGetter
// CredentialChecker provides an API for checking that the credentials
// used by the broker are functioning.
CredentialChecker
// ApplicationBroker provides an API for accessing the broker interface
// for individual applications and watching their units.
ApplicationBroker
// ServiceManager provides an API for creating and watching services.
ServiceManager
// ModelOperatorManager provides an API for deploying operators for
// individual models.
ModelOperatorManager
// EnsureImageRepoSecret ensures the image pull secret gets created.
EnsureImageRepoSecret(context.Context, docker.ImageRepoDetails) error
// ProxyManager provides methods for managing application proxy connections.
ProxyManager
}
Broker instances interact with the CAAS substrate.
func New ¶
func New(ctx context.Context, args environs.OpenParams, invalidator environs.CredentialInvalidator) (Broker, error)
New returns a new broker based on the provided configuration.
func Open ¶
func Open(ctx context.Context, p environs.EnvironProvider, args environs.OpenParams, invalidator environs.CredentialInvalidator) (Broker, error)
Open creates a Broker instance and errors if the provider is not for a container substrate.
type CharmStorageParams ¶
type CharmStorageParams struct {
// Size is the minimum size of the filesystem in MiB.
Size uint64
// The provider type for this filesystem.
Provider storage.ProviderType
// Attributes is a set of provider-specific options for storage creation,
// as defined in a storage pool.
Attributes map[string]any
// ResourceTags is a set of tags to set on the created filesystem, if the
// storage provider supports tags.
ResourceTags map[string]string
}
CharmStorageParams defines parameters used to create storage for operators to use for charm state.
type ClusterVersionGetter ¶
type ClusterVersionGetter interface {
// Version returns cluster version information.
Version() (*semversion.Number, error)
}
ClusterVersionGetter provides methods to get cluster version information.
type ContainerConfig ¶
type ContainerConfig struct {
// Name of the container.
Name string
// Image used to create the container.
Image resource.DockerImageDetails
// Mounts to storage that are to be provided within this container.
Mounts []MountConfig
// Uid to run pebble as.
Uid *int
// Gid to run pebble as.
Gid *int
}
ContainerConfig describes a container that is deployed alonside the uniter/charm container.
type ContainerEnvironProvider ¶
type ContainerEnvironProvider interface {
environs.EnvironProvider
// Open opens the broker and returns it. The configuration must
// have passed through PrepareConfig at some point in its lifecycle.
//
// Open should not perform any expensive operations, such as querying
// the cloud API, as it will be called frequently.
Open(ctx context.Context, args environs.OpenParams, invalidator environs.CredentialInvalidator) (Broker, error)
}
ContainerEnvironProvider represents a computing and storage provider for a container runtime.
type CredentialChecker ¶
type CredentialChecker interface {
// CheckCloudCredentials verifies that the provided cloud credentials
// are still valid for the cloud.
CheckCloudCredentials(ctx context.Context) error
}
CredentialChecker provides an API for checking that the credentials used by the broker are functioning.
type DeploymentParams ¶
type DeploymentParams struct {
DeploymentType DeploymentType
ServiceType ServiceType
}
DeploymentParams defines parameters for specifying how a service is deployed.
type DeploymentState ¶
type DeploymentState struct {
// Exists is true if the operator/application exists in the cluster.
Exists bool
// Terminating is true if the operator/application is in Terminating state.
Terminating bool
}
DeploymentState is returned by the OperatorExists call.
type DeploymentType ¶
type DeploymentType string
DeploymentType defines a deployment type.
const ( DeploymentStateless DeploymentType = "stateless" DeploymentStateful DeploymentType = "stateful" DeploymentDaemon DeploymentType = "daemon" )
func (DeploymentType) Validate ¶
func (dt DeploymentType) Validate() error
Validate validates if this deployment type is supported.
type FilesystemInfo ¶
type FilesystemInfo struct {
StorageName string
PersistentVolumeClaimName string
Size uint64
MountPoint string
ReadOnly bool
Status status.StatusInfo
Volume VolumeInfo
}
FilesystemInfo represents information about a filesystem mounted by a unit.
type ModelOperatorConfig ¶
type ModelOperatorConfig struct {
// AgentConf is the contents of the agent.conf file.
AgentConf []byte
// ImageDetails is the docker registry URL and auth details for the juju operator image.
ImageDetails resource.DockerImageDetails
// Port is the socket port that the operator model will be listening on
Port int32
}
ModelOperatorConfig is the config to when creating a model operator
type ModelOperatorManager ¶
type ModelOperatorManager interface {
// ModelOperatorExists indicates if the model operator for the given broker
// exists
ModelOperatorExists(ctx context.Context) (bool, error)
// EnsureModelOperator creates or updates a model operator pod for running
// model operations in a CAAS namespace/model
EnsureModelOperator(ctx context.Context, modelUUID, agentPath string, config *ModelOperatorConfig) error
// ModelOperator return the model operator config used to create the current
// model operator for this broker
ModelOperator(ctx context.Context) (*ModelOperatorConfig, error)
// GetModelOperatorDeploymentImage returns the image used for the model operator deployment.
GetModelOperatorDeploymentImage(ctx context.Context) (string, error)
}
ModelOperatorManager provides an API for deploying operators for individual models.
type MountConfig ¶
type MountConfig struct {
// StorageName is the name of the storage as specified in the charm.
StorageName string
// Path is the mount point inside the container.
Path string
}
MountConfig describes a storage that should be mounted to a container.
type NewContainerBrokerFunc ¶
type NewContainerBrokerFunc func(ctx context.Context, args environs.OpenParams, invalidator environs.CredentialInvalidator) (Broker, error)
NewContainerBrokerFunc returns a Container Broker.
type Operator ¶
type Operator struct {
Id string
Dying bool
Status status.StatusInfo
Config *OperatorConfig
}
Operator represents information about the status of an "operator pod".
type OperatorConfig ¶
type OperatorConfig struct {
// ImageDetails is the docker registry URL and auth details for the juju operator image.
ImageDetails resource.DockerImageDetails
// BaseImageDetails is the docker registry URL and auth details for the charm base image.
BaseImageDetails resource.DockerImageDetails
// Version is the Juju version of the operator image.
Version semversion.Number
// CharmStorage defines parameters used to optionally
// create storage for operators to use for charm state.
CharmStorage *CharmStorageParams
// AgentConf is the contents of the agent.conf file.
AgentConf []byte
// OperatorInfo is the contents of the operator.yaml file.
OperatorInfo []byte
// ResourceTags is a set of tags to set on the operator pod.
ResourceTags map[string]string
// ConfigMapGeneration is set when updating the operator config
// map for consistency in Read after Write and Write after Write.
// A value of 0 is ignored.
ConfigMapGeneration int64
}
OperatorConfig is the config to use when creating an operator.
type ProxyManager ¶
type ProxyManager interface {
ProxyToApplication(ctx context.Context, appName, remotePort string) (proxy.Proxier, error)
}
ProxyManager provides the API to get proxier information for applications
type Service ¶
type Service struct {
Id string
Addresses network.ProviderAddresses
Scale *int
Generation *int64
Status status.StatusInfo
}
Service represents information about the status of a caas service entity.
type ServiceInterface ¶
type ServiceInterface interface {
// UpdateService updates the default service with specific service type and port mappings.
UpdateService(ServiceParam) error
UpdatePorts(ports []ServicePort, updateContainerPorts bool) error
}
ServiceInterface provides the API to get/set service.
type ServiceManager ¶
type ServiceManager interface {
// GetService returns the service for the specified application.
// If its address Service is absent, the result has an empty Id and no
// Addresses, but may still contain workload status and scale information.
// Absence alone does not return an error.
GetService(ctx context.Context, appName string, includeClusterIP bool) (*Service, error)
}
ServiceManager provides the API to manipulate services.
type ServiceParam ¶
type ServiceParam struct {
Type string `json:"type"`
Ports []ServicePort `json:"ports"`
}
ServiceParam defines parameters for an UpdateService request.
type ServiceParams ¶
type ServiceParams struct {
// Deployment defines how a service is deployed.
Deployment DeploymentParams
// ResourceTags is a set of tags to set on the created service.
ResourceTags map[string]string
// Constraints is a set of constraints on
// the workload containers.
Constraints constraints.Value
// Filesystems is a set of parameters for filesystems that should be created.
Filesystems []storage.KubernetesFilesystemParams
// Devices is a set of parameters for Devices that is required.
Devices []devices.KubernetesDeviceParams
// CharmModifiedVersion increases when the charm changes in some way.
CharmModifiedVersion int
// ImageDetails is the docker registry URL and auth details for the juju init container image.
ImageDetails resource.DockerImageDetails
}
ServiceParams defines parameters used to create a service.
type ServicePort ¶
type ServicePort struct {
Name string `json:"name"`
Port int `json:"port"`
TargetPort int `json:"target-port"`
Protocol string `json:"protocol"`
}
ServicePort represents service ports mapping from service to units.
type ServiceType ¶
type ServiceType string
ServiceType defines a service type.
const ( ServiceCluster ServiceType = "cluster" ServiceLoadBalancer ServiceType = "loadbalancer" ServiceExternal ServiceType = "external" ServiceOmit ServiceType = "omit" )
func (ServiceType) IsOmit ¶
func (st ServiceType) IsOmit() bool
IsOmit indicates if a service is required.
type StatusCallbackFunc ¶
type StatusCallbackFunc func(appName string, settableStatus status.Status, info string, data map[string]any) error
StatusCallbackFunc represents a function that can be called to report a status.
type StorageValidator ¶
type StorageValidator interface {
// ValidateStorageClass returns an error if the storage config is not valid.
ValidateStorageClass(ctx context.Context, config map[string]any) error
}
StorageValidator provides methods to validate storage.
type Unit ¶
type Unit struct {
Id string
Address string
FQDN string
Ports []string
Dying bool
Stateful bool
Status status.StatusInfo
FilesystemInfo []FilesystemInfo
}
Unit represents information about the status of a "pod".
type Upgrader ¶
type Upgrader interface {
// Upgrade sets the OCI image for the app to the specified version.
Upgrade(ctx context.Context, appName string, vers semversion.Number) error
}
Upgrader provides the API to perform upgrades.
type VolumeInfo ¶
type VolumeInfo struct {
PersistentVolumeName string
Size uint64
Persistent bool
Status status.StatusInfo
}
VolumeInfo represents information about a volume mounted by a unit.
Directories
¶
| Path | Synopsis |
|---|---|
|
clientconfig/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |