client

Documentation

Overview

Package client implements clusterctl client functionality.

Index

• Constants
• type AlphaClient
• type ApplyUpgradeOptions
• type CertManagerUpgradePlan
• type Client
  • func New(ctx context.Context, path string, options ...Option) (Client, error)
• type ClusterClientFactory
• type ClusterClientFactoryInput
• type Components
• type ComponentsOptions
• type ConfigMapSourceOptions
• type DeleteOptions
• type DescribeClusterOptions
• type GetClusterTemplateOptions
• type GetKubeconfigOptions
• type InitOptions
• type Kubeconfig
• type MoveOptions
• type Option
  • func InjectClusterClientFactory(factory ClusterClientFactory) Option
  • func InjectConfig(config config.Client) Option
  • func InjectRepositoryFactory(factory RepositoryClientFactory) Option
• type PlanUpgradeOptions
• type ProcessYAMLOptions
• type Processor
• type Provider
• type ProviderRepositorySourceOptions
• type ReaderSourceOptions
• type RepositoryClientFactory
• type RepositoryClientFactoryInput
• type RolloutPauseOptions
• type RolloutRestartOptions
• type RolloutResumeOptions
• type RolloutUndoOptions
• type Template
• type TopologyPlanOptions
• type TopologyPlanOutput
• type URLSourceOptions
• type UpgradePlan
• type YamlPrinter

Constants

const DefaultCustomTemplateConfigMapKey = "template"

DefaultCustomTemplateConfigMapKey where the workload cluster template is hosted.

const NoopProvider = "-"

NoopProvider determines if a provider passed in should behave as a no-op.

Types

type AlphaClient

type AlphaClient interface {
	// RolloutRestart provides rollout restart of cluster-api resources
	RolloutRestart(ctx context.Context, options RolloutRestartOptions) error
	// RolloutPause provides rollout pause of cluster-api resources
	RolloutPause(ctx context.Context, options RolloutPauseOptions) error
	// RolloutResume provides rollout resume of paused cluster-api resources
	RolloutResume(ctx context.Context, options RolloutResumeOptions) error
	// RolloutUndo provides rollout rollback of cluster-api resources
	//
	// Deprecated: RolloutUndo is deprecated and will be removed in one of the upcoming releases.
	RolloutUndo(ctx context.Context, options RolloutUndoOptions) error
	// TopologyPlan dry runs the topology reconciler
	//
	// Deprecated: TopologyPlan is deprecated and will be removed in one of the upcoming releases.
	TopologyPlan(ctx context.Context, options TopologyPlanOptions) (*TopologyPlanOutput, error)
}

AlphaClient exposes the alpha features in clusterctl high-level client library.

type ApplyUpgradeOptions

type ApplyUpgradeOptions struct {
	// Kubeconfig to use for accessing the management cluster. If empty, default discovery rules apply.
	Kubeconfig Kubeconfig

	// Contract defines the API Version of Cluster API (contract e.g. v1alpha4) the management cluster should upgrade to.
	// When upgrading by contract, the latest versions available will be used for all the providers; if you want
	// a more granular control on upgrade, use CoreProvider, BootstrapProviders, ControlPlaneProviders, InfrastructureProviders.
	Contract string

	// CoreProvider instance and version (e.g. [capi-system/]cluster-api:v1.1.5) to upgrade to. This field can be used as alternative to Contract.
	// Specifying a namespace is now optional and in the future it will be deprecated.
	CoreProvider string

	// BootstrapProviders instance and versions (e.g. [capi-kubeadm-bootstrap-system/]kubeadm:v1.1.5) to upgrade to. This field can be used as alternative to Contract.
	// Specifying a namespace is now optional and in the future it will be deprecated.
	BootstrapProviders []string

	// ControlPlaneProviders instance and versions (e.g. [capi-kubeadm-control-plane-system/]kubeadm:v1.1.5) to upgrade to. This field can be used as alternative to Contract.
	// Specifying a namespace is now optional and in the future it will be deprecated.
	ControlPlaneProviders []string

	// InfrastructureProviders instance and versions (e.g. [capa-system/]aws:v0.5.0) to upgrade to. This field can be used as alternative to Contract.
	// Specifying a namespace is now optional and in the future it will be deprecated.
	InfrastructureProviders []string

	// IPAMProviders instance and versions (e.g. ipam-system/infoblox:v0.0.1) to upgrade to. This field can be used as alternative to Contract.
	IPAMProviders []string

	// RuntimeExtensionProviders instance and versions (e.g. runtime-extension-system/test:v0.0.1) to upgrade to. This field can be used as alternative to Contract.
	RuntimeExtensionProviders []string

	// AddonProviders instance and versions (e.g. caaph-system/helm:v0.1.0) to upgrade to. This field can be used as alternative to Contract.
	AddonProviders []string

	// WaitProviders instructs the upgrade apply command to wait till the providers are successfully upgraded.
	WaitProviders bool

	// WaitProviderTimeout sets the timeout per provider upgrade.
	WaitProviderTimeout time.Duration
}

ApplyUpgradeOptions carries the options supported by upgrade apply.

type CertManagerUpgradePlan

type CertManagerUpgradePlan cluster.CertManagerUpgradePlan

CertManagerUpgradePlan defines the upgrade plan if cert-manager needs to be upgraded to a different version.

type Client

type Client interface {
	// GetProvidersConfig returns the list of providers configured for this instance of clusterctl.
	GetProvidersConfig() ([]Provider, error)

	// GetProviderComponents returns the provider components for a given provider with options including targetNamespace.
	GetProviderComponents(ctx context.Context, provider string, providerType clusterctlv1.ProviderType, options ComponentsOptions) (Components, error)

	// GenerateProvider returns the provider components for a given provider with options including targetNamespace.
	GenerateProvider(ctx context.Context, provider string, providerType clusterctlv1.ProviderType, options ComponentsOptions) (Components, error)

	// Init initializes a management cluster by adding the requested list of providers.
	Init(ctx context.Context, options InitOptions) ([]Components, error)

	// InitImages returns the list of images required for executing the init command.
	InitImages(ctx context.Context, options InitOptions) ([]string, error)

	// GetClusterTemplate returns a workload cluster template.
	GetClusterTemplate(ctx context.Context, options GetClusterTemplateOptions) (Template, error)

	// GetKubeconfig returns the kubeconfig of the workload cluster.
	GetKubeconfig(ctx context.Context, options GetKubeconfigOptions) (string, error)

	// Delete deletes providers from a management cluster.
	Delete(ctx context.Context, options DeleteOptions) error

	// Move moves all the Cluster API objects existing in a namespace (or from all the namespaces if empty) to a target management cluster.
	Move(ctx context.Context, options MoveOptions) error

	// PlanUpgrade returns a set of suggested Upgrade plans for the cluster.
	PlanUpgrade(ctx context.Context, options PlanUpgradeOptions) ([]UpgradePlan, error)

	// PlanCertManagerUpgrade returns a CertManagerUpgradePlan.
	PlanCertManagerUpgrade(ctx context.Context, options PlanUpgradeOptions) (CertManagerUpgradePlan, error)

	// ApplyUpgrade executes an upgrade plan.
	ApplyUpgrade(ctx context.Context, options ApplyUpgradeOptions) error

	// ProcessYAML provides a direct way to process a yaml and inspect its
	// variables.
	ProcessYAML(ctx context.Context, options ProcessYAMLOptions) (YamlPrinter, error)

	// DescribeCluster returns the object tree representing the status of a Cluster API cluster.
	DescribeCluster(ctx context.Context, options DescribeClusterOptions) (*tree.ObjectTree, error)

	// AlphaClient is an Interface for alpha features in clusterctl
	AlphaClient
}

Client is exposes the clusterctl high-level client library.

func New

func New(ctx context.Context, path string, options ...Option) (Client, error)

New returns a configClient.

type ClusterClientFactory

type ClusterClientFactory func(ClusterClientFactoryInput) (cluster.Client, error)

ClusterClientFactory is a factory of cluster.Client from a given input.

type ClusterClientFactoryInput

type ClusterClientFactoryInput struct {
	Kubeconfig Kubeconfig
	Processor  Processor
}

ClusterClientFactoryInput represents the inputs required by the factory.

type Components

type Components repository.Components

Components wraps a YAML file that defines the provider's components (CRDs, controller, RBAC rules etc.).

type ComponentsOptions

type ComponentsOptions repository.ComponentsOptions

ComponentsOptions wraps inputs to get provider's components.

type ConfigMapSourceOptions

type ConfigMapSourceOptions struct {
	// Namespace where the ConfigMap exists. If unspecified, the current namespace will be used.
	Namespace string

	// Name to read the workload cluster template from.
	Name string

	// DataKey where the workload cluster template is hosted. If unspecified, the
	// DefaultCustomTemplateConfigMapKey will be used.
	DataKey string
}

ConfigMapSourceOptions defines the options to be used when reading a workload cluster template from a ConfigMap.

type DeleteOptions

type DeleteOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// CoreProvider version (e.g. cluster-api:v1.1.5) to delete from the management cluster.
	CoreProvider string

	// BootstrapProviders and versions (e.g. kubeadm:v1.1.5) to delete from the management cluster.
	BootstrapProviders []string

	// InfrastructureProviders and versions (e.g. aws:v0.5.0) to delete from the management cluster.
	InfrastructureProviders []string

	// ControlPlaneProviders and versions (e.g. kubeadm:v1.1.5) to delete from the management cluster.
	ControlPlaneProviders []string

	// IPAMProviders and versions (e.g. infoblox:v0.0.1) to delete from the management cluster.
	IPAMProviders []string

	// RuntimeExtensionProviders and versions (e.g. test:v0.0.1) to delete from the management cluster.
	RuntimeExtensionProviders []string

	// AddonProviders and versions (e.g. helm:v0.1.0) to delete from the management cluster.
	AddonProviders []string

	// DeleteAll set for deletion of all the providers.
	DeleteAll bool

	// IncludeNamespace forces the deletion of the namespace where the providers are hosted
	// (and of all the contained objects).
	IncludeNamespace bool

	// IncludeCRDs forces the deletion of the provider's CRDs (and of all the related objects).
	IncludeCRDs bool

	// SkipInventory forces the deletion of the inventory items used by clusterctl to track providers.
	SkipInventory bool
}

DeleteOptions carries the options supported by Delete.

type DescribeClusterOptions

type DescribeClusterOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Namespace where the workload cluster is located. If unspecified, the current namespace will be used.
	Namespace string

	// ClusterName to be used for the workload cluster.
	ClusterName string

	// ShowOtherConditions is a list of comma separated kind or kind/name for which we should add the ShowObjectConditionsAnnotation
	// to signal to the presentation layer to show all the conditions for the objects.
	ShowOtherConditions string

	// ShowMachineSets instructs the discovery process to include machine sets in the ObjectTree.
	ShowMachineSets bool

	// ShowClusterResourceSets instructs the discovery process to include cluster resource sets in the ObjectTree.
	ShowClusterResourceSets bool

	// ShowTemplates instructs the discovery process to include infrastructure and bootstrap config templates in the ObjectTree.
	ShowTemplates bool

	// AddTemplateVirtualNode instructs the discovery process to group template under a virtual node.
	AddTemplateVirtualNode bool

	// Echo displays MachineInfrastructure or BootstrapConfig objects if the object's ready condition is true
	// or it has the same Status, Severity and Reason of the parent's object ready condition (it is an echo)
	Echo bool

	// Grouping groups machines objects in case the ready conditions
	// have the same Status, Severity and Reason.
	Grouping bool
}

DescribeClusterOptions carries the options supported by DescribeCluster.

type GetClusterTemplateOptions

type GetClusterTemplateOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// ProviderRepositorySource to be used for reading the workload cluster template from a provider repository;
	// only one template source can be used at time; if not other source will be set, a ProviderRepositorySource
	// will be generated inferring values from the cluster.
	ProviderRepositorySource *ProviderRepositorySourceOptions

	// URLSource to be used for reading the workload cluster template; only one template source can be used at time.
	URLSource *URLSourceOptions

	// ConfigMapSource to be used for reading the workload cluster template; only one template source can be used at time.
	ConfigMapSource *ConfigMapSourceOptions

	// TargetNamespace where the objects describing the workload cluster should be deployed. If unspecified,
	// the current namespace will be used.
	TargetNamespace string

	// ClusterName to be used for the workload cluster.
	ClusterName string

	// KubernetesVersion to use for the workload cluster. If unspecified, the value from os env variables
	// or the $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml or .cluster-api/clusterctl.yaml config file will be used.
	KubernetesVersion string

	// ControlPlaneMachineCount defines the number of control plane machines to be added to the workload cluster.
	// It can be set through the cli flag, CONTROL_PLANE_MACHINE_COUNT environment variable or will default to 1
	ControlPlaneMachineCount *int64

	// WorkerMachineCount defines number of worker machines to be added to the workload cluster.
	// It can be set through the cli flag, WORKER_MACHINE_COUNT environment variable or will default to 0
	WorkerMachineCount *int64

	// ListVariablesOnly sets the GetClusterTemplate method to return the list of variables expected by the template
	// without executing any further processing.
	ListVariablesOnly bool

	// YamlProcessor defines the yaml processor to use for the cluster
	// template processing. If not defined, SimpleProcessor will be used.
	YamlProcessor Processor
}

GetClusterTemplateOptions carries the options supported by GetClusterTemplate.

type GetKubeconfigOptions

type GetKubeconfigOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Namespace is the namespace in which secret is placed.
	Namespace string

	// WorkloadClusterName is the name of the workload cluster.
	WorkloadClusterName string
}

GetKubeconfigOptions carries all the options supported by GetKubeconfig.

type InitOptions

type InitOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// CoreProvider version (e.g. cluster-api:v1.1.5) to add to the management cluster. If unspecified, the
	// cluster-api core provider's latest release is used.
	CoreProvider string

	// BootstrapProviders and versions (e.g. kubeadm:v1.1.5) to add to the management cluster.
	// If unspecified, the kubeadm bootstrap provider's latest release is used.
	BootstrapProviders []string

	// InfrastructureProviders and versions (e.g. aws:v0.5.0) to add to the management cluster.
	InfrastructureProviders []string

	// ControlPlaneProviders and versions (e.g. kubeadm:v1.1.5) to add to the management cluster.
	// If unspecified, the kubeadm control plane provider latest release is used.
	ControlPlaneProviders []string

	// IPAMProviders and versions (e.g. infoblox:v0.0.1) to add to the management cluster.
	IPAMProviders []string

	// RuntimeExtensionProviders and versions (e.g. test:v0.0.1) to add to the management cluster.
	RuntimeExtensionProviders []string

	// AddonProviders and versions (e.g. helm:v0.1.0) to add to the management cluster.
	AddonProviders []string

	// TargetNamespace defines the namespace where the providers should be deployed. If unspecified, each provider
	// will be installed in a provider's default namespace.
	TargetNamespace string

	// LogUsageInstructions instructs the init command to print the usage instructions in case of first run.
	LogUsageInstructions bool

	// WaitProviders instructs the init command to wait till the providers are installed.
	WaitProviders bool

	// WaitProviderTimeout sets the timeout per provider wait installation
	WaitProviderTimeout time.Duration

	// IgnoreValidationErrors allows for skipping the validation of provider installs.
	// NOTE this should only be used for development
	IgnoreValidationErrors bool
	// contains filtered or unexported fields
}

InitOptions carries the options supported by Init.

type Kubeconfig

type Kubeconfig cluster.Kubeconfig

Kubeconfig is a type that specifies inputs related to the actual kubeconfig.

type MoveOptions

type MoveOptions struct {
	// FromKubeconfig defines the kubeconfig to use for accessing the source management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	FromKubeconfig Kubeconfig

	// ToKubeconfig defines the kubeconfig to use for accessing the target management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	ToKubeconfig Kubeconfig

	// Namespace where the objects describing the workload cluster exists. If unspecified, the current
	// namespace will be used.
	Namespace string

	// ExperimentalResourceMutatorFn accepts any number of resource mutator functions that are applied on all resources being moved.
	// This is an experimental feature and is exposed only from the library and not (yet) through the CLI.
	ExperimentalResourceMutators []cluster.ResourceMutatorFunc

	// FromDirectory apply configuration from directory.
	FromDirectory string

	// ToDirectory save configuration to directory.
	ToDirectory string

	// DryRun means the move action is a dry run, no real action will be performed.
	DryRun bool
}

MoveOptions carries the options supported by move.

type Option

type Option func(*clusterctlClient)

Option is a configuration option supplied to New.

func InjectClusterClientFactory

func InjectClusterClientFactory(factory ClusterClientFactory) Option

InjectClusterClientFactory allows to override the default factory used for creating ClusterClient objects.

func InjectConfig

func InjectConfig(config config.Client) Option

InjectConfig allows to override the default configuration client used by clusterctl.

func InjectRepositoryFactory

func InjectRepositoryFactory(factory RepositoryClientFactory) Option

InjectRepositoryFactory allows to override the default factory used for creating RepositoryClient objects.

type PlanUpgradeOptions

type PlanUpgradeOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty, default discovery rules apply.
	Kubeconfig Kubeconfig
}

PlanUpgradeOptions carries the options supported by upgrade plan.

type ProcessYAMLOptions

type ProcessYAMLOptions struct {
	ReaderSource *ReaderSourceOptions
	// URLSource to be used for reading the template
	URLSource *URLSourceOptions

	// SkipTemplateProcess return the list of variables expected by the template
	// without executing any further processing.
	SkipTemplateProcess bool
}

ProcessYAMLOptions are the options supported by ProcessYAML.

type Processor

type Processor yaml.Processor

Processor defines the methods necessary for creating a specific yaml processor.

type Provider

type Provider config.Provider

Provider defines a provider configuration.

type ProviderRepositorySourceOptions

type ProviderRepositorySourceOptions struct {
	// InfrastructureProvider to read the workload cluster template from. If unspecified, the default
	// infrastructure provider will be used if no other sources are specified.
	InfrastructureProvider string

	// Flavor defines The workload cluster template variant to be used when reading from the infrastructure
	// provider repository. If unspecified, the default cluster template will be used.
	Flavor string
}

ProviderRepositorySourceOptions defines the options to be used when reading a workload cluster template from a provider repository.

type ReaderSourceOptions

type ReaderSourceOptions struct {
	Reader io.Reader
}

ReaderSourceOptions define the options to be used when reading a template from an arbitrary reader.

type RepositoryClientFactory

type RepositoryClientFactory func(context.Context, RepositoryClientFactoryInput) (repository.Client, error)

RepositoryClientFactory is a factory of repository.Client from a given input.

type RepositoryClientFactoryInput

type RepositoryClientFactoryInput struct {
	Provider  Provider
	Processor Processor
}

RepositoryClientFactoryInput represents the inputs required by the factory.

type RolloutPauseOptions

type RolloutPauseOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Resources for the rollout command
	Resources []string

	// Namespace where the resource(s) live. If unspecified, the namespace name will be inferred
	// from the current configuration.
	Namespace string
}

RolloutPauseOptions carries the options supported by RolloutPause.

type RolloutRestartOptions

type RolloutRestartOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Resources for the rollout command
	Resources []string

	// Namespace where the resource(s) live. If unspecified, the namespace name will be inferred
	// from the current configuration.
	Namespace string
}

RolloutRestartOptions carries the options supported by RolloutRestart.

type RolloutResumeOptions

type RolloutResumeOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Resources for the rollout command
	Resources []string

	// Namespace where the resource(s) live. If unspecified, the namespace name will be inferred
	// from the current configuration.
	Namespace string
}

RolloutResumeOptions carries the options supported by RolloutResume.

type RolloutUndoOptions

type RolloutUndoOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Resources for the rollout command
	Resources []string

	// Namespace where the resource(s) live. If unspecified, the namespace name will be inferred
	// from the current configuration.
	Namespace string

	// Revision number to rollback to when issuing the undo command.
	ToRevision int64
}

RolloutUndoOptions carries the options supported by RolloutUndo.

type Template

type Template repository.Template

Template wraps a YAML file that defines the cluster objects (Cluster, Machines etc.).

type TopologyPlanOptions

type TopologyPlanOptions struct {
	// Kubeconfig defines the kubeconfig to use for accessing the management cluster. If empty,
	// default rules for kubeconfig discovery will be used.
	Kubeconfig Kubeconfig

	// Objs is the list of objects that are input to the topology plan (dry run) operation.
	// The objects can be among new/modified clusters, new/modifed ClusterClasses and new/modified templates.
	Objs []*unstructured.Unstructured

	// Cluster is the name of the cluster to dryrun reconcile if multiple clusters are affected by the input.
	Cluster string

	// Namespace is the target namespace for the operation.
	// This namespace is used as default for objects with missing namespaces.
	// If the namespace of any of the input objects conflicts with Namespace an error is returned.
	Namespace string
}

TopologyPlanOptions define options for TopologyPlan.

type TopologyPlanOutput

type TopologyPlanOutput = cluster.TopologyPlanOutput

TopologyPlanOutput defines the output of the topology plan operation.

type URLSourceOptions

type URLSourceOptions struct {
	// URL to read the workload cluster template from.
	URL string
}

URLSourceOptions defines the options to be used when reading a workload cluster template from an URL.

type UpgradePlan

type UpgradePlan cluster.UpgradePlan

UpgradePlan defines a list of possible upgrade targets for a management cluster.

type YamlPrinter

type YamlPrinter interface {
	// Variables required by the template.
	Variables() []string

	// Yaml returns yaml defining all the cluster template objects as a byte array.
	Yaml() ([]byte, error)
}

YamlPrinter exposes methods that prints the processed template and variables.