cloudconn

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package cloudconn holds named cloud account connections (preview). It stores non-secret settings and a credential reference only, and probes health through a read-only provider interface. No provider here creates or changes cloud resources.

Index

Constants

View Source
const (
	OracleConfigFileName = "config"
	OracleKeyFileName    = "oci_api_key.pem" //nolint:gosec // a file name, not a credential

)

File names inside a materialized OCI credential directory.

View Source
const (
	ProviderOracle       = "oracle"
	ProviderAWS          = "aws"
	ProviderAzure        = "azure"
	ProviderGCP          = "gcp"
	ProviderHetzner      = "hetzner"
	ProviderDigitalOcean = "digitalocean"

	AuthOIDCFederation = "oidc_federation"
	AuthRoleAssumption = "role_assumption"
	AuthSecretRef      = "secret_ref"
	AuthStatic         = "static"
)

Providers and auth methods accepted on a connection.

View Source
const (
	ClassOK                   = "ok"
	ClassUnsupported          = "unsupported"
	ClassConfigInvalid        = "config_invalid"
	ClassCredentialUnresolved = "credential_unresolved" //nolint:gosec // class name, not a credential
	ClassAuthFailed           = "auth_failed"
	ClassUnreachable          = "unreachable"
	ClassUnknown              = "unknown"
)

Health classes. A check reports one of these and nothing from the provider's own output.

Variables

View Source
var (
	ErrInvalid  = errors.New("cloudconn: invalid connection")
	ErrConflict = errors.New("cloudconn: connection name already in use")
	ErrNotFound = errors.New("cloudconn: connection not found")
)

Errors the API maps to status codes.

View Source
var ErrUnsupported = errors.New("cloudconn: not implemented for this provider")

ErrUnsupported marks a provider operation this build does not implement.

Functions

func PolicyStatements

func PolicyStatements(compartment, group string) ([]string, error)

PolicyStatements returns the least privilege OCI IAM policy the user applies themselves. Every statement is scoped to one compartment; Levelrail never creates IAM.

func SealOracleSecret

func SealOracleSecret(ctx context.Context, s SealedSetter, namespace, key string, sec OracleSecret) (string, error)

SealOracleSecret validates the secret, stores it sealed and returns the NAMESPACE/KEY reference a connection keeps. The key never reaches the connection row.

func ValidateOracle

func ValidateOracle(c OracleCredential) error

ValidateOracle checks every field offline: OCID shapes, region, fingerprint and the key.

func WithOracleCredential

func WithOracleCredential(base, mountDir string, c OracleCredential, fn func(*OracleCredFiles) error) (err error)

WithOracleCredential materializes the credential for fn and always removes it afterwards.

Types

type Config

type Config struct {
	Region         string `json:"region,omitempty"`
	AccountID      string `json:"account_id,omitempty"` // AWS account, OCI tenancy OCID, GCP project
	Compartment    string `json:"compartment,omitempty"`
	RoleARN        string `json:"role_arn,omitempty"`
	SubscriptionID string `json:"subscription_id,omitempty"`
	ResourceGroup  string `json:"resource_group,omitempty"`
	OIDCAudience   string `json:"oidc_audience,omitempty"`
}

Config holds the non-secret settings; which fields apply depends on the provider.

type Connection

type Connection struct {
	Name           string
	Provider       string
	TeamID         string
	AuthMethod     string
	Config         Config
	CredentialRef  string
	CreatedBy      string
	CreatedAt      time.Time
	UpdatedAt      time.Time
	LastCheckedAt  time.Time
	LastCheckClass string
}

Connection is one named cloud account. It never carries a credential value.

type Fake

type Fake struct {
	ProviderName string
	Class        string
	Err          error
	Regions      []string

	Checked []string
	CredLen []int
	// contains filtered or unexported fields
}

Fake is an in-memory provider for tests: it validates like the real config rules and returns a scripted class, recording the credential length it was handed.

func (*Fake) Check

func (f *Fake) Check(_ context.Context, t Target) (string, error)

Check returns the scripted class.

func (*Fake) ListRegions

func (f *Fake) ListRegions(context.Context, Target) ([]string, error)

ListRegions returns the scripted regions.

func (*Fake) Name

func (f *Fake) Name() string

Name returns the provider name the fake stands in for.

func (*Fake) ValidateConfig

func (f *Fake) ValidateConfig(cfg Config, authMethod string) error

ValidateConfig applies the shared per provider rules.

type HealthChecker

type HealthChecker interface {
	Check(ctx context.Context, c OracleCredential) (string, error)
}

HealthChecker makes one read-only call with an OCI credential and returns a Class constant.

type Input

type Input struct {
	Provider      string
	TeamID        string
	AuthMethod    string
	Config        Config
	CredentialRef string
}

Input creates or updates a connection. On update empty strings keep the stored value and a zero Config keeps the stored settings; Provider and Name never change.

type OracleCredFiles

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

OracleCredFiles is a materialized per-step credential. It exposes paths only.

func MaterializeOracle

func MaterializeOracle(base, mountDir string, c OracleCredential) (*OracleCredFiles, error)

MaterializeOracle writes an OCI config profile and key into a fresh 0700 directory under base (a tmpfs). mountDir is where the step sees that directory, so key_file resolves there.

func (*OracleCredFiles) Close

func (h *OracleCredFiles) Close() error

Close removes the directory; safe to call twice.

func (*OracleCredFiles) ConfigPath

func (h *OracleCredFiles) ConfigPath() string

ConfigPath is the host path of the OCI config file.

func (*OracleCredFiles) Dir

func (h *OracleCredFiles) Dir() string

Dir is the host directory holding config and key; mount it read-only into the step.

func (*OracleCredFiles) Redact

func (h *OracleCredFiles) Redact(line string) string

Redact scrubs the key material, whole or line by line, from a log line.

type OracleCredential

type OracleCredential struct {
	TenancyOCID     string
	CompartmentOCID string
	Region          string
	Secret          OracleSecret
}

OracleCredential is everything one OCI step needs. Tenancy, region and compartment come from the connection settings; IaC documents only name the connection.

func OpenOracleSealed

func OpenOracleSealed(ctx context.Context, r SealedReader, c Connection) (OracleCredential, error)

OpenOracleSealed opens the sealed bundle a static oracle connection references. The returned error never carries the bundle or the reference value.

func OracleFromTarget

func OracleFromTarget(t Target) (OracleCredential, error)

OracleFromTarget joins the stored settings with the resolved sealed bundle.

type OracleHTTPChecker

type OracleHTTPChecker struct {
	Client  *http.Client
	BaseURL func(region string) string
	Now     func() time.Time
}

OracleHTTPChecker lists at most one instance in the compartment, which the generated compartment policy allows, so a pass proves the key and the scope together.

func NewOracleHTTPChecker

func NewOracleHTTPChecker() OracleHTTPChecker

NewOracleHTTPChecker uses the public regional compute endpoint and an env bounded timeout.

func (OracleHTTPChecker) Check

Check signs and sends one GET. Provider output never leaves this function.

type OracleProvider

type OracleProvider struct {
	Checker HealthChecker
}

OracleProvider is the read-only OCI side. It is not in DefaultRegistry; wiring it is opt-in.

func NewOracleProvider

func NewOracleProvider() OracleProvider

NewOracleProvider returns a provider backed by the real signed HTTP checker.

func (OracleProvider) Check

func (p OracleProvider) Check(ctx context.Context, t Target) (string, error)

Check resolves the sealed bundle from the target and runs one read-only call.

func (OracleProvider) ListRegions

func (OracleProvider) ListRegions(context.Context, Target) ([]string, error)

ListRegions needs a tenancy wide read, which the compartment policy does not grant.

func (OracleProvider) Name

func (OracleProvider) Name() string

Name returns the provider name.

func (OracleProvider) ValidateConfig

func (OracleProvider) ValidateConfig(cfg Config, authMethod string) error

ValidateConfig applies the shared rules, then the OCI shapes.

type OracleSecret

type OracleSecret struct {
	UserOCID    string
	Fingerprint string
	// contains filtered or unexported fields
}

OracleSecret is the sealed half of an OCI connection: the user, the key fingerprint and the API signing key. Every formatter masks the key.

func NewOracleSecret

func NewOracleSecret(userOCID, fingerprint string, pemKey []byte) OracleSecret

NewOracleSecret copies the PEM so the caller can wipe its own buffer.

func ParseOracleSecret

func ParseOracleSecret(v secretsource.Value) (OracleSecret, error)

ParseOracleSecret decodes a resolved sealed bundle. Errors never echo the input.

func (OracleSecret) GoString

func (s OracleSecret) GoString() string

GoString masks the key for %#v.

func (OracleSecret) KeyPEM

func (s OracleSecret) KeyPEM() []byte

KeyPEM returns a copy of the key for one upload; the caller wipes it after use.

func (OracleSecret) MarshalJSON

func (s OracleSecret) MarshalJSON() ([]byte, error)

MarshalJSON keeps the key out of any API or log encoding of the struct.

func (OracleSecret) String

func (s OracleSecret) String() string

String masks the key.

type Provider

type Provider interface {
	Name() string
	// ValidateConfig checks the non-secret settings for the given auth method.
	ValidateConfig(cfg Config, authMethod string) error
	// Check makes one read-only call and returns a Class constant; detail stays inside the provider.
	Check(ctx context.Context, t Target) (string, error)
	// ListRegions returns region identifiers the credential can see, read-only.
	ListRegions(ctx context.Context, t Target) ([]string, error)
}

Provider is the read-only side of a cloud. Implementations must not create, change or delete anything in the account.

type Registry

type Registry map[string]Provider

Registry maps a provider name to its implementation.

func DefaultRegistry

func DefaultRegistry() Registry

DefaultRegistry registers every provider as not implemented. The real OCI, AWS and Azure clients need SDK dependencies this repo does not carry yet; adding them is an owner decision.

func FakeRegistry

func FakeRegistry(class string, err error) (Registry, map[string]*Fake)

FakeRegistry maps every provider name to a Fake sharing one script.

func (Registry) Names

func (r Registry) Names() []string

Names returns the registered provider names, sorted.

type Rows

type Rows interface {
	ListCloudConnections(ctx context.Context) ([]store.CloudConnection, error)
	GetCloudConnection(ctx context.Context, name string) (store.CloudConnection, error)
	CreateCloudConnection(ctx context.Context, c store.CloudConnection) error
	UpdateCloudConnection(ctx context.Context, c store.CloudConnection) error
	SetCloudConnectionCheck(ctx context.Context, name, class string, at time.Time) error
	DeleteCloudConnection(ctx context.Context, name string) error
}

Rows is the connection table.

type SealedReader

type SealedReader interface {
	Resolve(ctx context.Context, namespace, key string) (string, error)
}

SealedReader reads back a value SealOracleSecret stored; secrets.Manager satisfies it.

type SealedSetter

type SealedSetter interface {
	SetValue(ctx context.Context, namespace, key, plaintext string) error
}

SealedSetter stores a value sealed at rest; secrets.Manager satisfies it.

type Service

type Service struct {
	Rows      Rows
	Providers Registry
	// Sources resolves secret:// references for a probe; nil means references cannot be resolved.
	Sources *secretsource.Resolver
	Now     func() time.Time
}

Service owns the connection set and runs read-only probes.

func (*Service) Create

func (s *Service) Create(ctx context.Context, actor, name string, in Input) (Connection, error)

Create validates and stores a new connection.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, name string) error

Delete removes a connection.

func (*Service) Get

func (s *Service) Get(ctx context.Context, name string) (Connection, error)

Get returns one connection or ErrNotFound.

func (*Service) List

func (s *Service) List(ctx context.Context) ([]Connection, error)

List returns every connection ordered by name.

func (*Service) Test

func (s *Service) Test(ctx context.Context, name string) (TestResult, error)

Test runs one read-only probe and records its class. Provider text is never returned.

func (*Service) Update

func (s *Service) Update(ctx context.Context, name string, in Input) (Connection, error)

Update merges in over the stored connection, validates the result and saves it.

type Target

type Target struct {
	Connection Connection
	Credential secretsource.Value
}

Target is what a provider needs to probe one connection. Credential is zero for oidc_federation and masks itself when formatted.

type TestResult

type TestResult struct {
	OK     bool
	Class  string
	Reason string
}

TestResult is the outcome of a health probe. Reason comes from a fixed table, never from provider output.

Jump to

Keyboard shortcuts

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