cloud

package
v0.0.0-...-aca40d1 Latest Latest
Warning

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

Go to latest
Published: Jun 15, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package cloud defines the abstraction layer between the controllers and the STACKIT SDK. Controllers must not reach into the SDK directly; all calls go through the Client interface in this package.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound     = errors.New("not found")
	ErrUnauthorized = errors.New("unauthorized")
	ErrInvalidInput = errors.New("invalid input")
	ErrConflict     = errors.New("conflict")
	ErrTransient    = errors.New("transient")
)

Sentinel errors returned by Client implementations. Controllers use errors.Is to classify them into requeue / condition-update behavior.

View Source
var ErrInvalidProviderID = errors.New("invalid providerID")

ErrInvalidProviderID is returned by ParseProviderID for malformed values.

Functions

func CleanupByTags

func CleanupByTags(ctx context.Context, client Client, tags map[string]string) error

CleanupByTags deletes provider-managed cloud resources matching tags without relying on Kubernetes objects. Load balancers are deleted before servers so server deletion is not blocked by target attachments.

func IsConflict

func IsConflict(err error) bool

IsConflict reports whether err wraps ErrConflict.

func IsInvalidInput

func IsInvalidInput(err error) bool

IsInvalidInput reports whether err wraps ErrInvalidInput.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err wraps ErrNotFound.

func IsRetryable

func IsRetryable(err error) bool

IsRetryable reports whether err should trigger a requeue (conflict or transient).

func IsTransient

func IsTransient(err error) bool

IsTransient reports whether err wraps ErrTransient.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err wraps ErrUnauthorized.

func NewProviderID

func NewProviderID(projectID, region, serverID string) string

NewProviderID returns a providerID string in the STACKIT format used by cloud-provider-stackit.

Format verified against the local cloud-provider-stackit repository:

  • pkg/ccm/instances.go: Instances.makeInstanceID returns stackit://<server-id>
  • pkg/ccm/instances.go: instanceIDFromProviderID parses only the server ID

Project ID and region are intentionally not encoded in the providerID. The cloud-provider-stackit controller gets project and region from its own configuration and then resolves Node.spec.providerID via GetServer(projectID, region, serverID).

func ParseProviderID

func ParseProviderID(providerID string) (projectID, region, serverID string, err error)

ParseProviderID splits a providerID string into its components. The current STACKIT providerID format does not contain project or region, so those return values are empty. It returns ErrInvalidProviderID if any encoded component is empty or the scheme is wrong.

Types

type Address

type Address struct {
	Type    string
	Address string
}

Address is an IP or DNS endpoint of a Server.

type Bastion

type Bastion struct {
	ServerID        string
	ServerState     string
	PublicIPID      string
	PublicIP        string
	SecurityGroupID string
}

Bastion describes the provider-managed SSH bastion resources.

type BastionInput

type BastionInput struct {
	Name         string
	ProjectID    string
	Region       string
	NetworkID    string
	ImageID      string
	MachineType  string
	SSHKeyName   string
	AllowedCIDRs []string
	Tags         map[string]string
	RootVolume   RootVolumeInput
	CloudInit    []byte
}

BastionInput holds all parameters required to ensure a bastion host.

type Client

type Client interface {
	GetServer(ctx context.Context, id string) (*Server, error)

	FindServerByTags(ctx context.Context, tags map[string]string) (*Server, error)

	ListServersByTags(ctx context.Context, tags map[string]string) ([]*Server, error)

	CreateServer(ctx context.Context, input CreateServerInput) (*Server, error)

	DeleteServer(ctx context.Context, id string) error

	GetNetwork(ctx context.Context, id string) (*Network, error)

	EnsureBastion(ctx context.Context, input BastionInput) (*Bastion, error)

	DeleteBastion(ctx context.Context, input BastionInput, status Bastion) error

	EnsureNodeSSHAccess(ctx context.Context, input NodeSSHAccessInput) (*SecurityGroup, error)

	DeleteNodeSSHAccess(ctx context.Context, tags map[string]string) error

	ListPublicIPsByTags(ctx context.Context, tags map[string]string) ([]*PublicIP, error)

	ListSecurityGroupsByTags(ctx context.Context, tags map[string]string) ([]*SecurityGroup, error)

	EnsureAPIServerLoadBalancer(ctx context.Context, input LoadBalancerInput) (*LoadBalancer, error)

	ListAPIServerLoadBalancersByTags(ctx context.Context, tags map[string]string) ([]*LoadBalancer, error)

	EnsureAPIServerLoadBalancerTarget(ctx context.Context, input LoadBalancerTargetInput) error

	DeleteAPIServerLoadBalancerTarget(ctx context.Context, input LoadBalancerTargetInput) error

	DeleteAPIServerLoadBalancer(ctx context.Context, id string) error
}

Client is the abstraction over STACKIT cloud APIs used by the controllers.

Implementations must:

  • return ErrNotFound when a resource does not exist
  • return ErrUnauthorized for permanent auth failures
  • return ErrInvalidInput for permanent input validation errors
  • return ErrConflict for retryable conflict errors
  • return ErrTransient for retryable transient errors
  • be idempotent (CreateServer/EnsureAPIServerLoadBalancer must not produce duplicates when a resource with matching tags already exists)

func NewClient

func NewClient(_ context.Context, creds Credentials) (Client, error)

NewClient returns the real STACKIT cloud client.

The credential secret format mirrors machine-controller-manager-provider-stackit: "project-id" plus "serviceaccount.json". Authentication uses the STACKIT service-account key flow.

type CreateServerInput

type CreateServerInput struct {
	Name             string
	ProjectID        string
	Region           string
	ImageID          string
	MachineType      string
	AvailabilityZone string
	SSHKeyName       string
	NetworkID        string
	SecurityGroups   []string
	UserData         []byte
	Tags             map[string]string
	RootVolume       RootVolumeInput
}

CreateServerInput holds all parameters required to create a new VM.

type Credentials

type Credentials struct {
	ProjectID          string
	Region             string
	ServiceAccountJSON []byte
}

Credentials carries the materials needed to construct a STACKIT API client. For MVP we only need the service-account JSON and project ID.

type Factory

type Factory func(ctx context.Context, creds Credentials) (Client, error)

Factory builds a Client from credentials (raw bytes from the configured Secret) plus the project ID and region from the StackitCluster spec.

Controllers receive a Factory rather than a Client so that the real implementation can be swapped for the fake in tests.

type LoadBalancer

type LoadBalancer struct {
	ID      string
	Name    string
	IP      string
	DNSName string
	Port    int32
}

LoadBalancer describes an API-server load balancer.

type LoadBalancerInput

type LoadBalancerInput struct {
	Name      string
	ProjectID string
	Region    string
	NetworkID string
	Tags      map[string]string
	Port      int32
	Targets   []LoadBalancerTargetInput
}

LoadBalancerInput holds all parameters required to ensure an API-server LB.

type LoadBalancerTargetInput

type LoadBalancerTargetInput struct {
	LoadBalancerID string
	Name           string
	IP             string
	Port           int32
}

LoadBalancerTargetInput describes a VM target in the API-server load balancer target pool.

type Network

type Network struct {
	ID           string
	Name         string
	IPv4Prefixes []string
}

Network is an existing STACKIT virtual network referenced by the provider.

type NodeSSHAccessInput

type NodeSSHAccessInput struct {
	Name                   string
	ServerID               string
	BastionSecurityGroupID string
	Tags                   map[string]string
}

NodeSSHAccessInput holds parameters required to allow SSH from the bastion security group to cluster nodes.

type PublicIP

type PublicIP struct {
	ID                 string
	IP                 string
	NetworkInterfaceID string
}

PublicIP describes a STACKIT public IP resource.

type RootVolumeInput

type RootVolumeInput struct {
	SizeGiB             int
	PerformanceClass    string
	DeleteOnTermination bool
}

RootVolumeInput describes the root disk of a VM.

type SDKClient

type SDKClient struct {
	// contains filtered or unexported fields
}

SDKClient is the STACKIT SDK-backed implementation of Client.

func (*SDKClient) CreateServer

func (c *SDKClient) CreateServer(ctx context.Context, input CreateServerInput) (*Server, error)

func (*SDKClient) DeleteAPIServerLoadBalancer

func (c *SDKClient) DeleteAPIServerLoadBalancer(ctx context.Context, id string) error

func (*SDKClient) DeleteAPIServerLoadBalancerTarget

func (c *SDKClient) DeleteAPIServerLoadBalancerTarget(ctx context.Context, input LoadBalancerTargetInput) error

func (*SDKClient) DeleteBastion

func (c *SDKClient) DeleteBastion(ctx context.Context, input BastionInput, status Bastion) error

func (*SDKClient) DeleteNodeSSHAccess

func (c *SDKClient) DeleteNodeSSHAccess(ctx context.Context, tags map[string]string) error

func (*SDKClient) DeleteServer

func (c *SDKClient) DeleteServer(ctx context.Context, id string) error

func (*SDKClient) EnsureAPIServerLoadBalancer

func (c *SDKClient) EnsureAPIServerLoadBalancer(ctx context.Context, input LoadBalancerInput) (*LoadBalancer, error)

func (*SDKClient) EnsureAPIServerLoadBalancerTarget

func (c *SDKClient) EnsureAPIServerLoadBalancerTarget(ctx context.Context, input LoadBalancerTargetInput) error

func (*SDKClient) EnsureBastion

func (c *SDKClient) EnsureBastion(ctx context.Context, input BastionInput) (*Bastion, error)

func (*SDKClient) EnsureNodeSSHAccess

func (c *SDKClient) EnsureNodeSSHAccess(ctx context.Context, input NodeSSHAccessInput) (*SecurityGroup, error)

func (*SDKClient) FindServerByTags

func (c *SDKClient) FindServerByTags(ctx context.Context, tags map[string]string) (*Server, error)

func (*SDKClient) GetNetwork

func (c *SDKClient) GetNetwork(ctx context.Context, id string) (*Network, error)

func (*SDKClient) GetServer

func (c *SDKClient) GetServer(ctx context.Context, id string) (*Server, error)

func (*SDKClient) ListAPIServerLoadBalancersByTags

func (c *SDKClient) ListAPIServerLoadBalancersByTags(
	ctx context.Context,
	tags map[string]string,
) ([]*LoadBalancer, error)

func (*SDKClient) ListPublicIPsByTags

func (c *SDKClient) ListPublicIPsByTags(ctx context.Context, tags map[string]string) ([]*PublicIP, error)

func (*SDKClient) ListSecurityGroupsByTags

func (c *SDKClient) ListSecurityGroupsByTags(ctx context.Context, tags map[string]string) ([]*SecurityGroup, error)

func (*SDKClient) ListServersByTags

func (c *SDKClient) ListServersByTags(ctx context.Context, tags map[string]string) ([]*Server, error)

type SecurityGroup

type SecurityGroup struct {
	ID   string
	Name string
}

SecurityGroup describes a STACKIT security group.

type Server

type Server struct {
	ID         string
	Name       string
	State      string
	ProviderID string
	Addresses  []Address
}

Server describes a STACKIT compute instance in provider-neutral terms.

Directories

Path Synopsis
Package fake provides an in-memory cloud.Client used by unit and envtest tests.
Package fake provides an in-memory cloud.Client used by unit and envtest tests.