caas

package
v0.0.0-...-234537a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: AGPL-3.0 Imports: 17 Imported by: 47

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

View Source
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

View Source
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

type ApplicationState struct {
	DesiredReplicas int
	Replicas        []string
}

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

New returns a new broker based on the provided configuration.

func Open

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 DeploymentMode

type DeploymentMode string

DeploymentMode defines a deployment mode.

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 RunAs

type RunAs string

RunAs defines which user to run a certain process as.

const (
	RunAsDefault RunAs = ""
	RunAsRoot    RunAs = "root"
	RunAsSudoer  RunAs = "sudoer"
	RunAsNonRoot RunAs = "non-root"
)

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.
pod
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址