Documentation
¶
Index ¶
- Constants
- Variables
- func AuthToString[T any](sa *T) string
- func ConfigFilePath(workDir string, profile string) string
- func ConvertAuth[T any](auth AuthConfig, creds *T) error
- func ConvertDescriptor[T any](from any, to *T) (*T, error)
- func DomainInZone(domain, zone string) bool
- func IsComponentConfigTopLevelKey(key string) bool
- func IsEngineOnlyType(resourceType string) bool
- func IsSafeToReplace(resourceType string) bool
- func IsZoneApex(domain, zone string) bool
- func MarshalDescriptor[T any](descriptor *T) ([]byte, error)
- func MustClone[T any](original T) T
- func ParentStackName(ref string) string
- func ReadDescriptor[T any](filePath string, descriptor *T) (*T, error)
- func RegisterCloudComposeConverter(mapping CloudComposeConfigRegister)
- func RegisterCloudHelper(mapping CloudHelpersRegisterMap)
- func RegisterCloudSingleImageConverter(mapping CloudSingleImageConfigRegister)
- func RegisterCloudStaticSiteConverter(mapping CloudStaticSiteConfigRegister)
- func RegisterPluginOwnedType(name string, kind PluginOwnedKind, pluginName string)
- func RegisterPluginRequirement(req PluginRequirement)
- func RegisterPluginStackConverter(c PluginStackConverter)
- func RegisterProviderConfig(configMapping ConfigRegisterMap)
- func RegisterProvisioner(provisionerMapping ProvisionerRegisterMap)
- func RegisterProvisionerFieldConfig(mapping ProvisionerFieldConfigRegister)
- func RegisterSafeToReplaceType(resourceType string)
- func SafeToReplaceTypes() map[string]struct{}
- func SetLatestVersionResolver(fn func(repo string) (string, error)) func()
- func StackConfigDomainOf(cfg any) string
- func UnmarshalDescriptor[T any](bytes []byte) (*T, error)
- func ValidateComponentConfigs(descriptor *ServerDescriptor, v ComponentValidator) error
- func ValidatePluginRequirements(descriptor *ServerDescriptor) error
- type Alert
- type AlertSender
- type AlertType
- type AlertsConfig
- type AttachDescriptor
- type AuthConfig
- type AuthDescriptor
- type BuilderDescriptor
- type CacheDescriptor
- type CiCdDescriptor
- type ClientDescriptor
- func (s *ClientDescriptor) Copy() ClientDescriptor
- func (c *ClientDescriptor) GetDefaultValue(key string) (interface{}, bool)
- func (c *ClientDescriptor) GetDefaultsSection() map[string]interface{}
- func (c *ClientDescriptor) HasDefaults() bool
- func (c *ClientDescriptor) PluginClientConfigJSON() ([]byte, error)
- func (c *ClientDescriptor) ReuseExistingCommitTagEnabled() bool
- func (c *ClientDescriptor) SetDefaultValue(key string, value interface{})
- func (c *ClientDescriptor) SetDefaultsSection(defaults map[string]interface{})
- type CloudComposeConfigRegister
- type CloudComposeDescriptor
- type CloudHelper
- type CloudHelperInitFunc
- type CloudHelperOption
- type CloudHelperType
- type CloudHelpersRegisterMap
- type CloudSingleImageConfigRegister
- type CloudStaticSiteConfigRegister
- type CommonAlertConfig
- type ComponentConfig
- func (c *ComponentConfig) DeployTo() (string, error)
- func (c *ComponentConfig) Image() (string, error)
- func (c *ComponentConfig) ImageIsBuildSpec() bool
- func (c *ComponentConfig) IngressHostname() (string, error)
- func (c *ComponentConfig) IngressRegistrar() (string, error)
- func (c *ComponentConfig) Raw() map[string]any
- func (c *ComponentConfig) RawCopy() map[string]any
- func (c *ComponentConfig) ServiceEnv() (map[string]string, error)
- func (c *ComponentConfig) SigningKeyRef() (string, error)
- type ComponentValidator
- type ComputeEnvVariables
- type Config
- type ConfigFile
- type ConfigReaderFunc
- type ConfigRegisterMap
- type Container
- type ContainerImage
- type ContainerImageBuild
- type CorsConfig
- type Credentials
- type DefectDojoDescriptor
- type DeployParams
- type DestroyParams
- type DestroyResult
- type DiscordCfg
- type DnsConfigAware
- type DnsRecord
- type EmailCfg
- type Headers
- type ImageBuildDescriptor
- type ImagePlatform
- type Inherit
- type InitParams
- type MaxCPUConfig
- type MaxErrorConfig
- type MaxMemoryConfig
- type MetadataDescriptor
- type OutputDescriptor
- type OutputsResult
- type PRCommentDescriptor
- type ParentResourceDependency
- type PerEnvResourcesDescriptor
- type PerStackResourcesDescriptor
- type PluginClientConfig
- type PluginFieldConfig
- func (p *PluginFieldConfig) CredentialsValue() string
- func (p *PluginFieldConfig) DnsRecords() []DnsRecord
- func (p *PluginFieldConfig) IsProvisionEnabled() bool
- func (p *PluginFieldConfig) KeyUrl() string
- func (p *PluginFieldConfig) MarshalJSON() ([]byte, error)
- func (p *PluginFieldConfig) MarshalYAML() (interface{}, error)
- func (p *PluginFieldConfig) ProjectIdValue() string
- func (p *PluginFieldConfig) ProviderType() string
- func (p *PluginFieldConfig) StorageUrl() string
- func (p *PluginFieldConfig) UsesAmbientCredentials() bool
- func (p *PluginFieldConfig) Zones() []string
- type PluginOutputValue
- type PluginOwnedBinding
- type PluginOwnedKind
- type PluginPreparedInput
- func (p *PluginPreparedInput) DependsOnResources() []StackConfigDependencyResource
- func (p *PluginPreparedInput) MarshalJSON() ([]byte, error)
- func (p *PluginPreparedInput) OverriddenBaseZone() string
- func (p *PluginPreparedInput) StackConfigDomain() string
- func (p *PluginPreparedInput) Uses() []string
- type PluginRequirement
- type PluginResourceOutput
- type PluginSource
- type PluginSpec
- type PluginStackConvertRequest
- type PluginStackConvertResult
- type PluginStackConverter
- type PreviewResult
- type ProvenanceDescriptor
- type ProvisionParams
- type Provisioner
- type ProvisionerConfigAware
- type ProvisionerDescriptor
- type ProvisionerFieldConfigReadFunc
- type ProvisionerFieldConfigReaderFunc
- type ProvisionerFieldConfigRegister
- type ProvisionerInitFunc
- type ProvisionerOption
- type ProvisionerRegisterMap
- type ReadOpts
- type RefreshResult
- type RegistrarConfig
- type RegistrarDescriptor
- type RegistrarZonesAware
- type RemoteImage
- type ReplaceRule
- type ReportingDescriptor
- type ResourceAware
- type ResourceDescriptor
- type ResourceInput
- type ResourceOutput
- type ResourceRef
- type ResponseTimeConfig
- type SBOMDescriptor
- type ScanDescriptor
- type ScanToolDescriptor
- type SecretsConfigDescriptor
- type SecretsDescriptor
- type SecretsProviderConfig
- type SecurityDescriptor
- type ServerDescriptor
- func DetectCiCdType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func DetectProvisionerType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func DetectResourcesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func DetectSecretsType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func DetectTemplatesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func ReadServerConfigs(descriptor *ServerDescriptor) (*ServerDescriptor, error)
- func ReadServerDescriptor(path string) (*ServerDescriptor, error)
- type ServerErrorsConfig
- type SigningDescriptor
- type SimpleContainerLBConfig
- type SlackCfg
- type Stack
- type StackClientDescriptor
- type StackConfigCompose
- type StackConfigComposeResources
- type StackConfigComposeScale
- type StackConfigComposeScaleCpu
- type StackConfigComposeScaleMemory
- type StackConfigComposeScalePolicy
- type StackConfigComposeSize
- type StackConfigDependencyResource
- type StackConfigSingleImage
- type StackConfigStatic
- type StackDescriptor
- func DetectTemplateType(tpl StackDescriptor) (*StackDescriptor, error)
- func PrepareClientConfigForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, ...) (*StackDescriptor, error)
- func PrepareCloudComposeForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, ...) (*StackDescriptor, error)
- func PrepareCloudSingleImageForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, ...) (*StackDescriptor, error)
- func PrepareStaticForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, ...) (*StackDescriptor, error)
- type StackParams
- type StacksMap
- type StateStorageConfig
- type StaticSiteConfig
- type TelegramCfg
- type TextVolume
- type Timeouts
- type ToCloudComposeConvertFunc
- type ToCloudSingleImageConvertFunc
- type ToCloudStaticSiteConvertFunc
- type UnhealthyHostsConfig
- type UpdateResult
- type VariableDescriptor
- type VariableValues
- type VerifyDescriptor
- type VmConfigAware
- type WithCopy
- type WithDependencyProviders
- type WithDependsOnResources
- type WithParentDependencies
- type WithProviderType
Constants ¶
const ( ClientSchemaVersion = "1.0" ClientTypeCloudCompose = "cloud-compose" ClientTypeStatic = "static" ClientTypeSingleImage = "single-image" )
const ( ComposeLabelIngressContainer = "simple-container.com/ingress" ComposeLabelVolumeSize = "simple-container.com/volume-size" ComposeLabelVolumeAccessModes = "simple-container.com/volume-access-modes" ComposeLabelVolumeStorageClass = "simple-container.com/volume-storage-class" ComposeLabelIngressPort = "simple-container.com/ingress/port" ComposeLabelHealthcheckSuccessCodes = "simple-container.com/healthcheck/success-codes" ComposeLabelHealthcheckHealthyThreshold = "simple-container.com/healthcheck/healthy-threshold" ComposeLabelHealthcheckPath = "simple-container.com/healthcheck/path" ComposeLabelHealthcheckPort = "simple-container.com/healthcheck/port" )
const ( ScConfigDirectory = ".sc" EnvConfigFileTemplate = "cfg.%s.yaml" ScConfigEnvVariable = "SIMPLE_CONTAINER_CONFIG" ScContainerResourceTypeEnvVariable = "SIMPLE_CONTAINER_RESOURCE_TYPE" )
const ( ServerDescriptorFileName = "server.yaml" SecretsDescriptorFileName = "secrets.yaml" ClientDescriptorFileName = "client.yaml" )
const ( // ServerSchemaVersion is the DEFAULT value SC uses when writing a new // server.yaml. Not a required pin — an empty schemaVersion field is // treated as the 1.0-compatible lenient mode. ServerSchemaVersion = "1.0" // ServerSchemaVersion11 is the strict-mode version. Setting // `schemaVersion: 1.1` in server.yaml opts into: // - `plugins:` MUST declare any out-of-tree plugin-owned type the // stack uses. No GitHub auto-inject fallback. // - Unknown schemaVersion strings fail at parse time. // 1.0 (or empty) keeps the pre-A3 lenient behaviour. ServerSchemaVersion11 = "1.1" // UpgradingToPluginsDocsURL is the migration guide operators are // pointed at from every plugin-related parse error. Keep in one place // so a URL change in the docs site is a single edit here. UpgradingToPluginsDocsURL = "https://docs.simple-container.com/guides/upgrading-to-plugins/" )
const DefaultRegistrarName = ""
DefaultRegistrarName is the key the legacy single `registrar:` block is normalised under. It is deliberately the empty string so that anything derived from a registrar's name is unchanged for stacks written before `registrars:` existed.
const ResourceRefPrefix = "${resource:"
ResourceRefPrefix is the placeholder context this reference uses.
It is deliberately the same `${resource:<name>.<key>}` spelling a CLIENT stack already uses to read a provisioned parent resource's outputs (see pkg/clouds/pulumi/api/compute_context.go) — one syntax, one meaning, two tiers. The RESOLUTION is necessarily different: a client-stack placeholder is substituted as a string before anything runs, while here the value does not exist until the sibling has been provisioned in this very update, so it can only ever be a Pulumi Output.
That is also why the reference survives placeholder resolution untouched. `pkg/provisioner/placeholders` registers no `resource` extension, and pkg/template's calcValue returns an unknown context verbatim rather than erroring (strict mode is off on the provision path) — so the literal string arrives at the provisioning tier for ParseResourceRef to read. Registering a `resource` extension in that package would silently break every reference here.
const SecretsSchemaVersion = "1.0"
Variables ¶
var ( ReadIgnoreNoClientCfg = ReadOpts{IgnoreClientMissing: true} ReadIgnoreNoServerCfg = ReadOpts{IgnoreServerMissing: true, IgnoreSecretsMissing: true} ReadIgnoreNoSecretsAndClientCfg = ReadOpts{IgnoreSecretsMissing: true, IgnoreClientMissing: true} ReadIgnoreNoSecretsAndServerCfg = ReadOpts{IgnoreSecretsMissing: true, IgnoreServerMissing: true} ReadIgnoreNoAnyCfg = ReadOpts{IgnoreSecretsMissing: true, IgnoreServerMissing: true, IgnoreClientMissing: true} // ReadSecretsOnly is for a command that wants a stack's secret values and // nothing else — it tolerates a missing client.yaml and asks the read not // to pay the plugin pre-parse. The server descriptor is still read (a // scoped secrets store needs its provisioner config), just cheaply when // that is possible. See ReadOpts.PluginTypesNotNeeded. ReadSecretsOnly = ReadOpts{IgnoreClientMissing: true, PluginTypesNotNeeded: true} )
var ComponentConfigTopLevelKeys = []string{
"deployTo",
"image",
"signingKey",
"env",
"ingress",
}
ComponentConfigTopLevelKeys lists the keys the Component class treats as well-known on the resource's config. Any additional top-level key an operator or plugin tries to set that is NOT also listed in the per-type allowlist is a parse-time error (plugin_requirements.go).
Kept as a var (not const slice) so test fixtures and future components can extend it if they need to. Changes here are plugin-facing-contract changes — review against the design doc before touching.
var ComputeEnv = ComputeEnvVariables{ CloudHelperType: "SIMPLE_CONTAINER_CLOUD_HELPER_TYPE", DiscordWebhookUrl: "SIMPLE_CONTAINER_DISCORD_WEBHOOK_URL", SlackWebhookUrl: "SIMPLE_CONTAINER_SLACK_WEBHOOK_URL", TelegramChatID: "SIMPLE_CONTAINER_TELEGRAM_CHAT_ID", TelegramToken: "SIMPLE_CONTAINER_TELEGRAM_TOKEN", AlertName: "SIMPLE_CONTAINER_ALERT_NAME", AlertDescription: "SIMPLE_CONTAINER_ALERT_DESCRIPTION", StackName: "SIMPLE_CONTAINER_STACK", StackEnv: "SIMPLE_CONTAINER_ENV", StackVersion: "SIMPLE_CONTAINER_VERSION", CloudProvider: "SIMPLE_CONTAINER_CLOUD", CtLogGroupName: "SIMPLE_CONTAINER_CT_LOG_GROUP_NAME", CtLogGroupRegion: "SIMPLE_CONTAINER_CT_LOG_GROUP_REGION", CtFilterPattern: "SIMPLE_CONTAINER_CT_FILTER_PATTERN", }
var ErrPluginUnimplementedConversion = stderrors.New("plugin does not implement ConvertStackConfig")
ErrPluginUnimplementedConversion is the sentinel the stackread converter returns when a plugin's binary predates the ConvertStackConfig RPC (gRPC Unimplemented). SC core treats this as "the plugin cannot answer the RPC yet" and falls through to the pre-A2 cloud*ConverterMapping path, which is still populated via each plugin's /api/init.go blank-imports — strictly additive.
Rationale: new RPCs on the SCCloudPlugin service must be forward- and backward-compatible, so a CLI release that adds a required RPC does not break every deployed stack whose pinned plugin binary predates it. This sentinel is the mechanism; the standing rule for every future new RPC is to catch Unimplemented at the dial site and fall through to a known-good legacy path (if one exists) or return a legible operator error (if not).
Peer-flagged root cause of the ConvertStackConfig fleet break 2026-11-02: api #535 shipped the caller + no plugin release had the handler + forge's aws pin predated the handler. Every isolated-matrix deploy hit "ConvertStackConfig: Unimplemented". With this fallback, that failure mode becomes silent: the plugin says Unimplemented, SC core uses the typed-converter mapping, deploy proceeds as it did before A2.
var ErrServerDescriptorInvalid = errors.New("server descriptor exists but is invalid")
ErrServerDescriptorInvalid tags the case where a stack's server.yaml EXISTS but could not be parsed or failed validation. It must never be conflated with "server.yaml is absent": ReadOpts.IgnoreServerMissing legitimately tolerates a client-only stack directory, but silently dropping a malformed or rejected server.yaml discards the only actionable diagnosis the operator will ever get and surfaces much later as a generic "provisioner is not set for stack %q". Same principle as scoped.ErrScopedIntegrity on the secrets path — a config we could not read is never treated as "simply absent". See ReadStacks.
var SupportedServerSchemaVersions = map[string]bool{ ServerSchemaVersion: true, ServerSchemaVersion11: true, }
SupportedServerSchemaVersions lists every value `schemaVersion:` may legally hold. An empty string is treated as implicit 1.0 and does not need to appear here; the validator special-cases it.
Functions ¶
func AuthToString ¶
func ConfigFilePath ¶
func ConvertAuth ¶
func ConvertAuth[T any](auth AuthConfig, creds *T) error
func ConvertDescriptor ¶
func DomainInZone ¶
DomainInZone reports whether a domain is served by a DNS zone — the zone itself, or anything under it. Both sides are compared without a trailing dot and without regard to case, and a match must land on a label boundary so that `notsimple-forge.com` is not read as being inside `simple-forge.com`.
func IsComponentConfigTopLevelKey ¶
IsComponentConfigTopLevelKey reports whether the given key is one of the well-known Component config keys above.
func IsEngineOnlyType ¶
IsEngineOnlyType reports whether the type is rule 3 — a resource with no cloud counterpart. Exported separately because it is the one rule SafeToReplaceTypes cannot enumerate: a prefix is not a finite set.
func IsSafeToReplace ¶
IsSafeToReplace reports whether `OpReplace` on this resource type should be exempt from the destructive-replace guard — under either rule. This is the single question the guard asks.
func IsZoneApex ¶
IsZoneApex reports whether a domain IS the zone rather than a name under it. The distinction decides which record type may point the name at a hostname: a CNAME is illegal at an apex, because the apex already holds the zone's own SOA and NS records and a CNAME may not coexist with other data (RFC 1034 §3.6.2). Every provider answers that with a non-standard record of its own, so the caller has to know which end of the zone it is writing.
func MarshalDescriptor ¶
func MustClone ¶
func MustClone[T any](original T) T
MustClone creates a deep copy of any value using YAML marshaling/unmarshaling This generic function works with any type T and handles complex nested structures automatically It is nil-safe and will return the zero value for nil inputs
func ParentStackName ¶
ParentStackName returns the stack name of a client's parent reference, which is either the bare name, "org/name" or "org/project/name".
func ReadDescriptor ¶
func RegisterCloudComposeConverter ¶
func RegisterCloudComposeConverter(mapping CloudComposeConfigRegister)
func RegisterCloudHelper ¶
func RegisterCloudHelper(mapping CloudHelpersRegisterMap)
func RegisterCloudSingleImageConverter ¶
func RegisterCloudSingleImageConverter(mapping CloudSingleImageConfigRegister)
func RegisterCloudStaticSiteConverter ¶
func RegisterCloudStaticSiteConverter(mapping CloudStaticSiteConfigRegister)
func RegisterPluginOwnedType ¶
func RegisterPluginOwnedType(name string, kind PluginOwnedKind, pluginName string)
RegisterPluginOwnedType records that the named type is owned by a plugin binary (its Schema RPC advertised it). Installs an opaque decoder into providerConfigMapping so the generic parse path at pkg/api/read.go recognises the type without needing a Go-link-time struct. The decoder preserves Config.Config as a map[string]any — the plugin receives the raw YAML tree on the provision bus and decodes it into its own typed Input shape there.
If the type was already registered via api.RegisterProviderConfig (an in-tree type or a plugin's /api/init.go typed registration), the typed decoder wins — do NOT overwrite it. This keeps the pre-parse strictly ADDITIVE: a plugin that cached /api still gives SC core the richer parse-time validation it had, and types SC core has never heard of fall through to the opaque path.
pluginName is the key under server.yaml's `plugins:` block (the stackread caller passes it through from descriptor.Plugins). The A2 ConvertStackConfig path uses it to dial the right plugin.
func RegisterPluginRequirement ¶
func RegisterPluginRequirement(req PluginRequirement)
RegisterPluginRequirement declares that a plugin owns a set of type tokens. Called at init() time from each sc-plugin's /api module. Idempotent — a repeated registration with the same name updates the owned-types list and the default source.
func RegisterPluginStackConverter ¶
func RegisterPluginStackConverter(c PluginStackConverter)
RegisterPluginStackConverter installs the dialling implementation (currently stackread.ConvertPluginStackConfig). SC core distributions that never spawn plugins (schema-gen, test fixtures that don't declare plugins:) can leave this nil — the Prepare*ForDeploy fallback is to try the in-tree cloud*ConverterMapping first and only reach for a plugin converter when the type is plugin-owned AND the converter is registered. A nil converter on a plugin-owned template is a configuration error, not a crash.
func RegisterProviderConfig ¶
func RegisterProviderConfig(configMapping ConfigRegisterMap)
func RegisterProvisioner ¶
func RegisterProvisioner(provisionerMapping ProvisionerRegisterMap)
func RegisterProvisionerFieldConfig ¶
func RegisterProvisionerFieldConfig(mapping ProvisionerFieldConfigRegister)
func RegisterSafeToReplaceType ¶
func RegisterSafeToReplaceType(resourceType string)
RegisterSafeToReplaceType adds a Pulumi resource type to the safe-to-replace allowlist. Safe to call concurrently. Idempotent.
Called by `pkg/stackread.DiscoverPluginTypes` for every entry in a plugin's `scpluginv1.SchemaResponse.safe_to_replace_types`; may also be called directly from init() by in-tree code that owns a revision-based type (keep that path rare — plugin advertisement is the preferred shape).
func SafeToReplaceTypes ¶
func SafeToReplaceTypes() map[string]struct{}
SafeToReplaceTypes returns a snapshot of every exempt type named EXACTLY — rules 1 and 2 — for tests and for operator-visible diagnostics ("sc explain"-style). Returned map is a copy; callers may mutate it without affecting the registry.
Rule 3 is absent and cannot be added: it is prefix-matched, so it denotes an open set with no enumeration. A caller deciding whether a specific type is exempt must ask SafeToReplaceRule or IsSafeToReplace, never membership of this map.
func SetLatestVersionResolver ¶
SetLatestVersionResolver replaces the plugin-release resolver and returns a func that restores the previous one. Defer the result.
This exists because auto-injection reaches api.github.com, and a unit test in ANY package that parses a server.yaml using a plugin-owned type without a `plugins:` pin will silently make that call. That is not hypothetical: it is how pkg/provisioner's own fool-protector test started hitting the network the moment auto-injection landed, passing or failing depending on whether the runner had egress. Tests that exercise either path must stub the resolver.
func StackConfigDomainOf ¶
StackConfigDomainOf returns the `domain:` an operator declared on a client stack, by TYPE rather than by marshalling.
Why a type switch and not a JSON probe. The domain lives in a different place per config shape — flat on compose and single-image, nested inside StaticSiteConfig on static — and `StackConfigStatic.Site` is a NAMED field tagged `json:",inline"`, which encoding/json does not inline. Any probe over marshalled JSON therefore has to know that `Site` becomes a capital-S nested object, and the next config shape that grows an inline-tagged named field breaks it again. The compiler knows all of this; a probe only guesses. See forge/docs/roadmap/items/plugin-bus-json-yaml-inline-tag-asymmetry.md.
Returns "" for a worker-only stack that declares no domain, which is a legitimate answer and not an error.
func UnmarshalDescriptor ¶
func ValidateComponentConfigs ¶
func ValidateComponentConfigs(descriptor *ServerDescriptor, v ComponentValidator) error
ValidateComponentConfigs walks a server descriptor and validates every resource whose type is a declared Component (per the supplied validator) against the §P1 config shape — top-level keys, deployTo-template existence, image shape, signingKey as a secret reference, and the plugin-override allowlist.
Intended to run AFTER the pre-engine plugin bundle has registered sidecars (so the validator's IsComponentType returns true for live plugin types). Called from pkg/clouds/pulumi/provisioner.go right after RegisterSidecars.
Pure: no mutation of the descriptor. Multiple validation errors in a descriptor are collected and surfaced in one error message rather than one-by-one.
Design: forge/docs/design/2026-11-10/sc-components-platform/README.md §P1.
func ValidatePluginRequirements ¶
func ValidatePluginRequirements(descriptor *ServerDescriptor) error
ValidatePluginRequirements walks every type token used in a ServerDescriptor and, for any token owned by an un-declared plugin, resolves the latest release from GitHub and injects a synthetic `plugins:` entry into the descriptor. Only when resolution itself fails (offline, rate-limited, repo gone) does it return an error — with the exact YAML block the operator needs to paste by hand.
Call this at the END of server.yaml parsing (ReadServerConfigs), BEFORE any Pulumi engine starts. The point is to make an existing server.yaml that predates the plugin split keep working across the upgrade: before this, parsing succeeded (the plugin /api module's blank import registers the type reader) and the deploy then died mid-provision with `unsupported registrar type "cloudflare"`, possibly after state had already been mutated.
Auto-injection — rather than a hard error — is deliberate: backwards compatibility means the upgrade must WORK, not merely diagnose. The resolver is skipped entirely for any plugin the operator did declare, so a pinned (reproducible) steady-state deploy makes no network call.
Types ¶
type Alert ¶
type Alert struct {
Name string `json:"name" yaml:"name"`
Title string `json:"title" yaml:"title"`
Reason string `json:"reason" yaml:"reason"`
Description string `json:"description" yaml:"description"`
StackName string `json:"stackName" yaml:"stackName"`
StackEnv string `json:"stackEnv" yaml:"stackEnv"`
DetailsUrl string `json:"detailsUrl" yaml:"detailsUrl"`
AlertType AlertType `json:"alertType" yaml:"alertType"`
CommitAuthor string `json:"commitAuthor,omitempty" yaml:"commitAuthor,omitempty"`
CommitMessage string `json:"commitMessage,omitempty" yaml:"commitMessage,omitempty"`
}
type AlertSender ¶
type AlertType ¶
type AlertType string
const ( // Monitoring Alert Types AlertTriggered AlertType = "TRIGGERED" AlertResolved AlertType = "RESOLVED" // Build/Deployment Notification Types BuildStarted AlertType = "BUILD_STARTED" BuildSucceeded AlertType = "BUILD_SUCCEEDED" BuildFailed AlertType = "BUILD_FAILED" BuildCancelled AlertType = "BUILD_CANCELLED" )
type AlertsConfig ¶
type AlertsConfig struct {
MaxCPU *MaxCPUConfig `json:"maxCPU,omitempty" yaml:"maxCPU,omitempty"`
MaxMemory *MaxMemoryConfig `json:"maxMemory,omitempty" yaml:"maxMemory,omitempty"`
MaxErrors *MaxErrorConfig `json:"maxErrors,omitempty" yaml:"maxErrors,omitempty"`
ServerErrors *ServerErrorsConfig `json:"serverErrors,omitempty" yaml:"serverErrors,omitempty"`
UnhealthyHosts *UnhealthyHostsConfig `json:"unhealthyHosts,omitempty" yaml:"unhealthyHosts,omitempty"`
ResponseTime *ResponseTimeConfig `json:"responseTime,omitempty" yaml:"responseTime,omitempty"`
Discord *DiscordCfg `json:"discord,omitempty" yaml:"discord,omitempty"`
Slack *SlackCfg `json:"slack,omitempty" yaml:"slack,omitempty"`
Telegram *TelegramCfg `json:"telegram,omitempty" yaml:"telegram,omitempty"`
Email *EmailCfg `json:"email,omitempty" yaml:"email,omitempty"`
}
type AttachDescriptor ¶
type AttachDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"` // Default: true
Sign bool `json:"sign,omitempty" yaml:"sign,omitempty"` // Sign the attestation
}
AttachDescriptor configures attestation attachment
type AuthConfig ¶
type AuthConfig interface {
WithProviderType
CredentialsValue() string
ProjectIdValue() string
}
AuthConfig defines configuration for a single cloud provider
type AuthDescriptor ¶
type AuthDescriptor struct {
Type string `json:"type" yaml:"type"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func DetectAuthProvider ¶
func DetectAuthProvider(auth *AuthDescriptor) (*AuthDescriptor, error)
func ParseAuthDescriptor ¶
func ParseAuthDescriptor(text string) (AuthDescriptor, error)
ParseAuthDescriptor reads one auth entry, written as the YAML that sits under its name in a secrets.yaml `auth:` map, and converts its config to the provider's type. A standalone entry has no parent to inherit from, so inherit is refused.
func (*AuthDescriptor) AuthConfig ¶
func (a *AuthDescriptor) AuthConfig() (AuthConfig, error)
func (*AuthDescriptor) Copy ¶
func (s *AuthDescriptor) Copy() AuthDescriptor
type BuilderDescriptor ¶
type BuilderDescriptor struct {
ID string `json:"id,omitempty" yaml:"id,omitempty"` // Auto-detected from CI if not specified
}
BuilderDescriptor configures builder identification
type CacheDescriptor ¶
type CacheDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
TTL string `json:"ttl,omitempty" yaml:"ttl,omitempty"`
Dir string `json:"dir,omitempty" yaml:"dir,omitempty"`
}
CacheDescriptor configures local artifact caching.
type CiCdDescriptor ¶
type CiCdDescriptor struct {
Type string `json:"type" yaml:"type"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func (*CiCdDescriptor) Copy ¶
func (s *CiCdDescriptor) Copy() CiCdDescriptor
type ClientDescriptor ¶
type ClientDescriptor struct {
SchemaVersion string `json:"schemaVersion" yaml:"schemaVersion"`
Defaults map[string]interface{} `json:"defaults,omitempty" yaml:"defaults,omitempty"` // Maximum flexibility - supports any user-defined YAML anchors, templates, and configuration
Stacks map[string]StackClientDescriptor `json:"stacks" yaml:"stacks"`
Security *SecurityDescriptor `json:"security,omitempty" yaml:"security,omitempty"` // Container security configuration
ImageBuild *ImageBuildDescriptor `json:"imageBuild,omitempty" yaml:"imageBuild,omitempty"`
}
ClientDescriptor describes the client schema
func ClientDescriptorFromPluginConfig ¶
func ClientDescriptorFromPluginConfig(raw []byte) (ClientDescriptor, error)
ClientDescriptorFromPluginConfig rebuilds the client descriptor a plugin's template reads from the JSON PluginClientConfigJSON wrote. Empty input is the zero descriptor: an older core sends none, and a plugin must run as it did.
func ReadClientDescriptor ¶
func ReadClientDescriptor(path string) (*ClientDescriptor, error)
func (*ClientDescriptor) Copy ¶
func (s *ClientDescriptor) Copy() ClientDescriptor
func (*ClientDescriptor) GetDefaultValue ¶
func (c *ClientDescriptor) GetDefaultValue(key string) (interface{}, bool)
GetDefaultValue retrieves a specific value from the defaults section Supports nested access using dot notation (e.g., "stack.type", "config.baseDnsZone")
func (*ClientDescriptor) GetDefaultsSection ¶
func (c *ClientDescriptor) GetDefaultsSection() map[string]interface{}
GetDefaultsSection returns the defaults section as a map for flexible access This allows users to define any YAML anchors and templates they need
func (*ClientDescriptor) HasDefaults ¶
func (c *ClientDescriptor) HasDefaults() bool
HasDefaults checks if the client configuration has a defaults section
func (*ClientDescriptor) PluginClientConfigJSON ¶
func (c *ClientDescriptor) PluginClientConfigJSON() ([]byte, error)
PluginClientConfigJSON serialises the client-level configuration a plugin's template needs, or nil when the descriptor sets none of it.
func (*ClientDescriptor) ReuseExistingCommitTagEnabled ¶
func (c *ClientDescriptor) ReuseExistingCommitTagEnabled() bool
ReuseExistingCommitTagEnabled reports whether tag reuse is configured.
func (*ClientDescriptor) SetDefaultValue ¶
func (c *ClientDescriptor) SetDefaultValue(key string, value interface{})
SetDefaultValue sets a specific value in the defaults section
func (*ClientDescriptor) SetDefaultsSection ¶
func (c *ClientDescriptor) SetDefaultsSection(defaults map[string]interface{})
SetDefaultsSection sets the entire defaults section (used for programmatic configuration)
type CloudComposeConfigRegister ¶
type CloudComposeConfigRegister map[string]ToCloudComposeConvertFunc
type CloudComposeDescriptor ¶
type CloudComposeDescriptor struct {
StackName string `json:"stackName" yaml:"stackName"`
StackDescriptor `json:",inline" yaml:",inline"`
}
type CloudHelper ¶
func NewCloudHelper ¶
func NewCloudHelper(chType string, opts ...CloudHelperOption) (CloudHelper, error)
type CloudHelperInitFunc ¶
type CloudHelperInitFunc func(opts ...CloudHelperOption) (CloudHelper, error)
type CloudHelperOption ¶
type CloudHelperOption func(c CloudHelper) error
func WithLogger ¶
func WithLogger(l logger.Logger) CloudHelperOption
type CloudHelperType ¶
type CloudHelperType string
type CloudHelpersRegisterMap ¶
type CloudHelpersRegisterMap map[CloudHelperType]CloudHelperInitFunc
func GetRegisteredCloudHelpers ¶
func GetRegisteredCloudHelpers() CloudHelpersRegisterMap
GetRegisteredCloudHelpers returns all registered cloud helper configurations Used by schema generator to automatically discover cloud helper types
type CloudSingleImageConfigRegister ¶
type CloudSingleImageConfigRegister map[string]ToCloudSingleImageConvertFunc
type CloudStaticSiteConfigRegister ¶
type CloudStaticSiteConfigRegister map[string]ToCloudStaticSiteConvertFunc
type CommonAlertConfig ¶
type ComponentConfig ¶
type ComponentConfig struct {
// contains filtered or unexported fields
}
ComponentConfig wraps *PluginFieldConfig with typed accessors that read its `.Raw` map, for the SC Components class of plugins (slice 1a of the sc-components-platform milestone).
Why a .Raw-reading wrapper rather than a Go interface satisfied by the plugin's typed config struct: the production `sc` binary reaches plugins exclusively via hashicorp/go-plugin gRPC and does NOT link plugin `/api` modules. A plugin-owned config value arrives at core as opaque *PluginFieldConfig, carrying the operator's YAML in `.Raw`. A Go interface defined in core cannot be satisfied by a type living in a plugin repo — the assertion is structurally guaranteed to fail in prod, even when a local test (which links the plugin's `/api`) shows it passing. 7+ exposures of that trap in the first fortnight of the plugin-split work; see the operator memory `interface_assertion_against_plugin_owned_value_fails_in_prod` + the parent `local_shape_not_production_shape`.
Full design: forge/docs/design/2026-11-10/sc-components-platform/ §P1 (Path A — Schema-advertised + .Raw-reading).
func NewComponentConfig ¶
func NewComponentConfig(cfg any) (*ComponentConfig, error)
NewComponentConfig wraps cfg as a ComponentConfig.
Accepted inputs:
- *PluginFieldConfig — the production path. `cfg.Raw` is the source of truth for all accessor reads.
- map[string]any — the test path. Lifts the map into a synthetic *PluginFieldConfig so test fixtures can skip the plugin-bus round trip.
- nil — returns a typed error rather than a nil-wrapped zero value.
Any other concrete type is a programmer error and returns an error naming the actual Go type.
func (*ComponentConfig) DeployTo ¶
func (c *ComponentConfig) DeployTo() (string, error)
DeployTo reads `.Raw["deployTo"]` as a non-empty string.
func (*ComponentConfig) Image ¶
func (c *ComponentConfig) Image() (string, error)
Image reads `.Raw["image"]` as EITHER a non-empty string reference (`"registry/repo:tag"`) OR a build-spec map (`{dockerfile: ..., build: {args: ...}}`). Both shapes are fleet-canonical:
- **String** — `image: simplecontainer/sc-backup:v1.2.3`. Component plugin pre-built the image + published it (or it's a public image). The dispatched template consumes the reference verbatim.
- **Map** — `image: {dockerfile: ${git:root}/Dockerfile, build: {args: {...}}}`. SC's own image-build-and-push flow builds the image at provision time and pushes to the operator's ECR under the fleet AWS account. This is the shape every forge-* service uses today.
Returns the string reference when `image` is a string. Returns an empty string when `image` is a map — the dispatched template reads the map shape directly from the merged config, and the empty return signals "no pre-built reference; template does the build." Required: `image` must be present and either shape; missing or wrong type → typed error naming the resource.
This replaces the string-only variant that shipped in slice 1a; caught at the first fleet smoke 2026-11-12 when the smoke-sc-components stack used the map shape per forge-notifier's template.
func (*ComponentConfig) ImageIsBuildSpec ¶
func (c *ComponentConfig) ImageIsBuildSpec() bool
ImageIsBuildSpec returns true when `.Raw["image"]` is a map (the build-at-deploy-time shape), false when it's a string reference. The sidecar wrapper uses this to decide whether to pass `image` through to the dispatched template as a reference or as a build spec.
func (*ComponentConfig) IngressHostname ¶
func (c *ComponentConfig) IngressHostname() (string, error)
IngressHostname reads `.Raw["ingress"].(map)["hostname"]` as a string. Absent hostname (or absent ingress block) returns "" + nil.
func (*ComponentConfig) IngressRegistrar ¶
func (c *ComponentConfig) IngressRegistrar() (string, error)
IngressRegistrar reads `.Raw["ingress"].(map)["registrar"]` as a string. Absent returns "" + nil (component defaults to the parent's default registrar).
func (*ComponentConfig) Raw ¶
func (c *ComponentConfig) Raw() map[string]any
Raw returns the underlying `.Raw` map. Callers must treat it as read-only; use RawCopy for a defensive copy.
func (*ComponentConfig) RawCopy ¶
func (c *ComponentConfig) RawCopy() map[string]any
RawCopy returns a shallow defensive copy of the underlying `.Raw` map so callers (e.g. the sidecar's merge logic) can mutate without disturbing the wrapped config.
func (*ComponentConfig) ServiceEnv ¶
func (c *ComponentConfig) ServiceEnv() (map[string]string, error)
ServiceEnv reads `.Raw["env"]` as a map[string]string. Absent key returns an empty map + nil. Values are coerced to string from map[string]any; non-string values are a shape error.
func (*ComponentConfig) SigningKeyRef ¶
func (c *ComponentConfig) SigningKeyRef() (string, error)
SigningKeyRef reads `.Raw["signingKey"]`. Absent key returns "" + nil (a component without a signingKey is a valid shape; the plugin's ComputeProcess will refuse to mint JWTs without it, but that's a runtime concern).
NOTE: a `${secret:...}` reference pattern check used to live here. Removed 2026-11-11 after the first slice-1a smoke caught that SC core resolves `${secret:...}` → value BEFORE ValidateComponentConfigs runs, so the parse-time pattern check always sees the resolved value and can never pass. Operators who want this field encrypted at rest should declare `signingKey: ${secret:...}` — SC's secret-resolution handles that; this accessor just validates presence + non-empty.
type ComponentValidator ¶
type ComponentValidator interface {
IsComponentType(typeToken string) bool
IsOverrideAllowed(typeToken, key string) bool
TemplateTypeExists(templateType string) bool
// HasInTreeMerge reports whether the given template type has an in-tree
// ComponentTemplateMergeFunc registration (e.g. vm-compose). For types
// that do, the merge func consumes the component's fields inside core
// before the template's ProvisionFunc runs, so the plugin-side
// SupportsComponent opt-in (below) is not required.
HasInTreeMerge(templateType string) bool
// AnyPluginSupportsComponent reports whether any loaded plugin has
// advertised supports_component for the given template type via Schema
// (slice 1a.1 of sc-components-platform; design doc §#19 path (b)). A
// plugin that has not opted in cannot receive the ComponentRaw
// side-channel on its Provision RPC; parse-time validation refuses any
// dispatch targeting such a template, unless the type has an in-tree
// merge func.
AnyPluginSupportsComponent(templateType string) bool
}
ComponentValidator is the signature for a callback that validates a single Component resource's config against SC core's set of known Component types. Implementations live in `pkg/clouds/pulumi/api` where the fleet-wide registration maps (ComponentResourceTypes, ComponentAllowedOverrides, ProvisionFuncByType) live; this package stays free of pulumi imports.
The validator reports back the component-resource type, the location in the descriptor, and an error if invalid. Nil return means ok.
type ComputeEnvVariables ¶
type ComputeEnvVariables struct {
DiscordWebhookUrl string
SlackWebhookUrl string
TelegramChatID string
TelegramToken string
AlertName string
AlertDescription string
StackName string
StackEnv string
CloudHelperType string
StackVersion string
// CloudProvider names the cloud a service was deployed to. It exists
// because Yandex does not identify itself at runtime — its Serverless
// Containers runtime defines exactly PORT and REQUEST_PATH, neither of
// which names the cloud — so go-aws-lambda-sdk reads this to decide
// whether to serve HTTP or start the Lambda runtime loop.
CloudProvider string
// CloudTrail enrichment: when all three are set on the alert Lambda,
// the handler looks up matching CloudTrail events in the alarm's time
// window and includes a short summary (who/what/when) in the Slack/
// Discord/Telegram notification.
CtLogGroupName string
CtLogGroupRegion string
CtFilterPattern string
}
type Config ¶
type Config struct {
Config any `json:"config" yaml:"config"`
}
type ConfigFile ¶
type ConfigFile struct {
ProjectName string `json:"projectName" yaml:"projectName"`
PrivateKeyPath string `yaml:"privateKeyPath,omitempty" json:"privateKeyPath,omitempty"`
PublicKeyPath string `yaml:"publicKeyPath,omitempty" json:"publicKeyPath,omitempty"`
PrivateKey string `yaml:"privateKey,omitempty" json:"privateKey,omitempty"`
PrivateKeyPassword string `yaml:"privateKeyPassword,omitempty" json:"privateKeyPassword,omitempty"`
PublicKey string `yaml:"publicKey,omitempty" json:"publicKey,omitempty"`
StacksDir string `yaml:"stacksDir,omitempty" json:"stacksDir,omitempty"`
ParentRepository string `yaml:"parentRepository,omitempty" json:"parentRepository,omitempty"`
}
func ReadConfigFile ¶
func ReadConfigFile(workDir, profile string) (*ConfigFile, error)
func (*ConfigFile) ToYaml ¶
func (f *ConfigFile) ToYaml() ([]byte, error)
func (*ConfigFile) WriteConfigFile ¶
func (f *ConfigFile) WriteConfigFile(workDir, profile string) error
type ConfigReaderFunc ¶
type ConfigRegisterMap ¶
type ConfigRegisterMap map[string]ConfigReaderFunc
func GetRegisteredProviderConfigs ¶
func GetRegisteredProviderConfigs() ConfigRegisterMap
GetRegisteredProviderConfigs returns all registered provider configurations Used by schema generator to automatically discover all resource types
type Container ¶
type Container struct {
ContainerImage `json:",inline" yaml:",inline"`
Name string `json:"name" yaml:"name"`
}
type ContainerImage ¶
type ContainerImage struct {
Name string `json:"name" yaml:"name"`
Dockerfile string `json:"dockerfile" yaml:"dockerfile"`
Context string `json:"context" yaml:"context"`
Build *ContainerImageBuild `json:"build" yaml:"build"`
Platform ImagePlatform `json:"platform" yaml:"platform"`
}
type ContainerImageBuild ¶
type CorsConfig ¶
type Credentials ¶
type Credentials struct {
Credentials string `json:"credentials" yaml:"credentials"` // required for proper deserialization
}
type DefectDojoDescriptor ¶
type DefectDojoDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
URL string `json:"url,omitempty" yaml:"url,omitempty"`
APIKey string `json:"apiKey,omitempty" yaml:"apiKey,omitempty"`
EngagementID int `json:"engagementId,omitempty" yaml:"engagementId,omitempty"`
EngagementName string `json:"engagementName,omitempty" yaml:"engagementName,omitempty"`
ProductID int `json:"productId,omitempty" yaml:"productId,omitempty"`
ProductName string `json:"productName,omitempty" yaml:"productName,omitempty"`
TestType string `json:"testType,omitempty" yaml:"testType,omitempty"`
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
Environment string `json:"environment,omitempty" yaml:"environment,omitempty"`
AutoCreate bool `json:"autoCreate,omitempty" yaml:"autoCreate,omitempty"`
}
DefectDojoDescriptor configures DefectDojo upload.
func (*DefectDojoDescriptor) Sanitize ¶
func (d *DefectDojoDescriptor) Sanitize() DefectDojoDescriptor
Sanitize returns a copy of this descriptor with the API key replaced by a placeholder string, safe for logging or debug serialization.
type DeployParams ¶
type DeployParams struct {
StackParams `json:",inline" yaml:",inline"`
Vars VariableValues `json:"vars" yaml:"vars"`
}
type DestroyParams ¶
type DestroyParams struct {
StackParams `json:",inline" yaml:",inline"`
DestroySecretsStack bool `json:"destroySecretsStack" yaml:"destroySecretsStack"`
}
type DestroyResult ¶
func (*DestroyResult) String ¶
func (r *DestroyResult) String() string
type DiscordCfg ¶
type DiscordCfg struct {
WebhookUrl string `json:"webhookUrl" yaml:"webhookUrl"`
}
type DnsConfigAware ¶
type DnsConfigAware interface {
OverriddenBaseZone() string
}
type DnsRecord ¶
type DnsRecord struct {
Name string `json:"name" yaml:"name"`
Type string `json:"type" yaml:"type"`
// ValueOut threads a Pulumi Output through in-process callers so a
// record's value can be a resolved resource property. It is not
// serializable (sdk.StringOutput's MarshalJSON refuses) and must be
// excluded from JSON/YAML marshaling — the plugin bus serializer in
// pkg/clouds/pulumi/plugin_sidecars.go would otherwise fail the entire
// config serialization and leave the plugin without accountId/zoneName.
ValueOut sdk.StringOutput `json:"-" yaml:"-"`
Value string `json:"value" yaml:"value"`
Proxied bool `json:"proxied" yaml:"proxied"`
// Priority is used by MX / SRV / URI record types and ignored by
// every other type (CNAME / A / TXT etc.). Nilable so the common
// case (non-MX records) marshals as empty rather than `priority: 0`,
// which cloudflare-pulumi's Record resource treats as a value
// rather than "unset" and sends to the API — producing an MX with
// priority 0 where the operator intended "not applicable".
// pulumi-cloudflare/sdk/v6 Record documents: "Required for MX, SRV
// and URI records; unused by other record types."
Priority *int `json:"priority,omitempty" yaml:"priority,omitempty"`
}
type EmailCfg ¶
type EmailCfg struct {
Addresses []string `json:"addresses,omitempty" yaml:"addresses,omitempty"`
}
type ImageBuildDescriptor ¶
type ImageBuildDescriptor struct {
// ReuseExistingCommitTag makes a deploy reuse the image already in the
// registry when the version already names a commit and is already present,
// instead of pushing a rebuild over it. Only versions of the form
// YYYY.MM.DD-<abbreviated commit sha> qualify. Defaults to false.
ReuseExistingCommitTag bool `json:"reuseExistingCommitTag,omitempty" yaml:"reuseExistingCommitTag,omitempty"`
}
ImageBuildDescriptor configures how images are built and pushed.
type ImagePlatform ¶
type ImagePlatform string
const (
ImagePlatformLinuxAmd64 ImagePlatform = "linux/amd64"
)
type Inherit ¶
type Inherit struct {
Inherit string `json:"inherit" yaml:"inherit"`
}
func (Inherit) IsInherited ¶
type InitParams ¶
type InitParams struct {
ProjectName string `json:"projectName" yaml:"projectName"`
RootDir string `json:"rootDir,omitempty" yaml:"rootDir"`
Profile string `json:"profile,omitempty" yaml:"profile"`
SkipInitialCommit bool `json:"skipInitialCommit" yaml:"skipInitialCommit"`
SkipProfileCreation bool `json:"skipProfileCreation" yaml:"skipProfileCreation"`
SkipScDirCreation bool `json:"skipScDirCreation" yaml:"skipScDirCreation"`
IgnoreWorkdirErrors bool `json:"skipCreateConfigDir" yaml:"skipCreateConfigDir"`
GenerateKeyPair bool `json:"generateKeyPair" yaml:"generateKeyPair"`
}
type MaxCPUConfig ¶
type MaxCPUConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
}
type MaxErrorConfig ¶
type MaxErrorConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
ErrorLogMessageRegexp string `json:"errorLogMessageRegexp" yaml:"errorLogMessageRegexp"`
}
type MaxMemoryConfig ¶
type MaxMemoryConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
}
type MetadataDescriptor ¶
type MetadataDescriptor struct {
IncludeEnv bool `json:"includeEnv,omitempty" yaml:"includeEnv,omitempty"`
IncludeMaterials bool `json:"includeMaterials,omitempty" yaml:"includeMaterials,omitempty"`
}
MetadataDescriptor configures metadata collection
type OutputDescriptor ¶
type OutputDescriptor struct {
Local string `json:"local,omitempty" yaml:"local,omitempty"` // Local file path
Registry bool `json:"registry,omitempty" yaml:"registry,omitempty"` // Upload to registry
}
OutputDescriptor configures output destinations
type OutputsResult ¶
type PRCommentDescriptor ¶
type PRCommentDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Output string `json:"output,omitempty" yaml:"output,omitempty"`
}
PRCommentDescriptor configures markdown output for PR comment workflows.
type ParentResourceDependency ¶
type ParentResourceDependency struct {
Name string `json:"name" yaml:"name"`
}
ParentResourceDependency when a resource depends on resource within the same stack
type PerEnvResourcesDescriptor ¶
type PerEnvResourcesDescriptor struct {
Template string `json:"template" yaml:"template"`
Resources map[string]ResourceDescriptor `json:"resources" yaml:"resources"`
Inherit `json:",inline" yaml:",inline"`
}
func (*PerEnvResourcesDescriptor) Copy ¶
func (s *PerEnvResourcesDescriptor) Copy() PerEnvResourcesDescriptor
type PerStackResourcesDescriptor ¶
type PerStackResourcesDescriptor struct {
// Registrar is the legacy single-registrar form. Mutually exclusive with Registrars.
Registrar RegistrarDescriptor `json:"registrar" yaml:"registrar"`
// Registrars allows several registrars to coexist, each serving its own DNS zones.
// The one that handles a given domain is picked by zone suffix. See AllRegistrars.
Registrars map[string]RegistrarDescriptor `json:"registrars,omitempty" yaml:"registrars,omitempty"`
Resources map[string]PerEnvResourcesDescriptor `json:"resources" yaml:"resources"`
}
func DetectPerStackResourcesType ¶
func DetectPerStackResourcesType(p *PerStackResourcesDescriptor) (*PerStackResourcesDescriptor, error)
func DetectRegistrarType ¶
func DetectRegistrarType(p *PerStackResourcesDescriptor) (*PerStackResourcesDescriptor, error)
func (PerStackResourcesDescriptor) AllRegistrars ¶
func (s PerStackResourcesDescriptor) AllRegistrars() (map[string]RegistrarDescriptor, error)
AllRegistrars normalises the two ways a server.yaml may declare registrars — the legacy single `registrar:` block and the `registrars:` map — into a single map. Declaring both at once is an error rather than a silent precedence rule. The result is empty when no registrar is configured, which is a valid configuration.
func (*PerStackResourcesDescriptor) Copy ¶
func (s *PerStackResourcesDescriptor) Copy() PerStackResourcesDescriptor
type PluginClientConfig ¶
type PluginClientConfig struct {
Security *SecurityDescriptor `json:"security,omitempty"`
ImageBuild *ImageBuildDescriptor `json:"imageBuild,omitempty"`
}
PluginClientConfig is the part of the client descriptor that crosses the plugin bus with a template's Provision request: what docker.BuildAndPushImage reads off stack.Client. A plugin cannot rebuild it, because it builds its api.Stack from the request header alone.
type PluginFieldConfig ¶
type PluginFieldConfig struct {
TypeName string `json:"type" yaml:"type"`
Raw map[string]any `json:"-" yaml:"-"`
URL string `json:"url" yaml:"url"`
Credentials string `json:"credentials" yaml:"credentials"`
ProjectID string `json:"projectId" yaml:"projectId"`
Provision bool `json:"provision" yaml:"provision"`
}
PluginFieldConfig is the SC-core-side carrier for a provisioner-field config (state-storage or secrets-provider) that a plugin owns. Implements api.StateStorageConfig and api.AuthConfig minimally; the plugin itself has the authoritative view of its config via its own InitStateStore RPC.
func (*PluginFieldConfig) CredentialsValue ¶
func (p *PluginFieldConfig) CredentialsValue() string
CredentialsValue returns the string the placeholder resolver substitutes for `${auth:<name>}`. Two shapes:
- `.Credentials` is non-empty — a `credentials: "…"` key was declared in YAML (state-storage / secrets-provider form) — return it verbatim.
- `.Credentials` is empty but `.Raw` has entries — this is an AUTH block (aws-token, yc-service-account, cloudru-access-key, …). The pre-A3 typed AuthConfig impls returned `api.AuthToString(r)` in this case — a JSON serialisation of the whole struct — so a downstream plugin decoding `credentials: "…"` could parse the full account config. Mirror that here by marshalling Raw.
Returns empty string only when there is genuinely no credential material to expand (ambient-credential path; UsesAmbientCredentials relies on this).
func (*PluginFieldConfig) DnsRecords ¶
func (p *PluginFieldConfig) DnsRecords() []DnsRecord
DnsRecords implements api.RegistrarConfig for plugin-owned registrars (cloudflare, cloudru-dns, yc-dns, …). Reads the `dnsRecords` list out of the Raw map that pluginOwnedWrappingDecoder preserved — the plugin bus's RegistrarConfig type-assertion at pkg/clouds/pulumi/plugin_sidecars.go:382 required this method, and without it operator-declared `dnsRecords:` entries on a plugin-owned registrar were silently dropped on the wire. Live-caught 2026-11-03 against sc-plugin-cloudflare v2026.11.02-8b9eb75: a navizon-infra server.yaml with four `dnsRecords:` entries completed `sc provision` as `Resources: 2 unchanged` and never emitted any `cloudflare:index/record:Record`.
The `type` key is consulted first for the DnsRecord type field; a `proxied` key arrives from YAML as `bool` but the bus serialises the whole map through JSON, which keeps bools as bools in map[string]any, so no extra parsing is needed for this scalar — the map[string]any unmarshal path keeps them bool-typed.
func (*PluginFieldConfig) IsProvisionEnabled ¶
func (p *PluginFieldConfig) IsProvisionEnabled() bool
func (*PluginFieldConfig) KeyUrl ¶
func (p *PluginFieldConfig) KeyUrl() string
KeyUrl is the secrets-provider key reference. A plugin-owned provider used with `provision: false` names its key in `keyName` (the typed gcp-kms and aws-kms configs returned it from KeyUrl), so fall back to it when no `url` is set; otherwise login fails with "secrets provider key url is empty".
func (*PluginFieldConfig) MarshalJSON ¶
func (p *PluginFieldConfig) MarshalJSON() ([]byte, error)
MarshalJSON merges the Raw map with the typed fields so the plugin bus (pkg/clouds/pulumi.serializeConfigToInputs → json.Marshal → gRPC InputValue tree) carries the full operator-declared config, not just the four typed slots.
Two reasons this is needed. First, Raw holds operator-declared keys that have no typed slot — `bucketName` on state-storage, `keyName` on secrets-provider — and without merging them the plugin never sees them (`Raw` carries `json:"-"`). Second, the placeholder resolver (pkg/provisioner/placeholders) walks the typed fields BOTH as struct fields AND via the Raw map; both end up with resolved values post- Resolve. Merging in this order (Raw first, typed fields override) means a stray stale value in Raw is beaten by the typed field, so a re-run after an edit cannot ship pre-resolution data.
Live-caught 2026-11-03 on forge-conductor isolated verify run 41680853191: plugin received `credentials: "${auth:aws}"` because json.Marshal(*PluginFieldConfig) only emitted the four typed fields, and the resolver's path to one of them was obstructed by an unexported ancestor. Merging via Raw sidesteps that walker-path fragility: whichever route the resolver takes, the plugin bus sees the resolved value.
func (*PluginFieldConfig) MarshalYAML ¶
func (p *PluginFieldConfig) MarshalYAML() (interface{}, error)
MarshalYAML mirrors MarshalJSON for the yaml.v3 path. Parent-stack provisioning (pkg/clouds/pulumi/provision.go) `yaml.Marshal`s each StackDescriptor into a Pulumi-exported secret the child deploy later reads back via `yaml.Unmarshal`. Without a MarshalYAML, the default struct-tag path honours `yaml:"-"` on Raw and emits only the four typed slots — operator-declared keys that have no typed counterpart (`accountId`, `bucketName`, `zoneName`, …) silently disappear from the state, and the child deploy dials the plugin with an empty `accountId` → `ToPagesConfig` → `accountId is empty`.
Live-caught 2026-11-03 on navizon's cloudflare-static-website isolated-stack child deploy. Diagnosed by navizon session; same merge semantics as MarshalJSON.
func (*PluginFieldConfig) ProjectIdValue ¶
func (p *PluginFieldConfig) ProjectIdValue() string
func (*PluginFieldConfig) ProviderType ¶
func (p *PluginFieldConfig) ProviderType() string
func (*PluginFieldConfig) StorageUrl ¶
func (p *PluginFieldConfig) StorageUrl() string
func (*PluginFieldConfig) UsesAmbientCredentials ¶
func (p *PluginFieldConfig) UsesAmbientCredentials() bool
func (*PluginFieldConfig) Zones ¶
func (p *PluginFieldConfig) Zones() []string
Zones implements RegistrarZonesAware for a plugin-owned registrar.
Without this, no registrar config that core holds as an OPAQUE PluginFieldConfig can report its zones — and in the SHIPPED binary that is every plugin-owned registrar, because `cmd/sc` links no plugin's Go module at all (plugins are reached over hashicorp/go-plugin gRPC). `declaredZones` (pkg/clouds/pulumi/registrars.go) therefore read no zones, `multiRegistrar.forDomain` could not match, and every domain fell through to whichever registrar is marked `default: true`.
That is what broke the 2026-11-09 `.ru` landing: with Cloudflare as the fleet's default, `simple-forge.ru` routed to CLOUDFLARE, so
- the cloudflare plugin was asked to serve it and answered `error retrieving zone ID for domain "simple-forge.ru": 0 found`;
- and `provisionDomainRegistrar` computed `regType = cloudflare`, found that the YANDEX plugin does not serve that type, took its early return, and the yandex plugin refused with `no yc-dns registrar initialised that serves "simple-forge.ru"`.
Fixed by this method; `.ru` deployed green on v2026.11.45 with both preview and deploy logging `initialising yandex registrar for zone "simple-forge.ru"` → `ready; main domain is "simple-forge.ru"`.
A WARNING for anyone re-measuring this in a test. A test binary in `pkg/clouds/pulumi` sees `yc-dns` as a TYPED *yandex.RegistrarConfig, not as an opaque config, because a sibling test file (plugin_inputs_test.go) imports `sc-plugin-yandex/api` and that registers the typed decoder. The shipped binary does not:
go list -deps ./cmd/sc | grep -c sc-plugin-yandex -> 0 go list -deps -test ./pkg/clouds/pulumi | grep sc-plugin-yandex -> api
So a local test can show this bug as already-fixed when production has it, which is exactly what happened mid-investigation and briefly cost this fix a wrongful retraction. Measure the import graph before trusting a Go type observed in a test.
The information was never missing — `Raw` carries the operator's `zoneName:` verbatim. Nothing read it.
Both spellings are accepted because both are in use: a single `zoneName:` (cloudflare, yc-dns) and a `zones:` list. A registrar that declares neither returns nil and keeps the old behaviour — it can still be the stack's only registrar, or its default.
type PluginOutputValue ¶
PluginOutputValue is one value a plugin published from its ProvisionResponse, carrying the plugin's own `secret` flag alongside it.
The flag is not decoration. A consumer that renders a value into a config file, a command line or a Pulumi input has to know whether to wrap it in `sdk.ToSecret` first: an HMAC secret key or a database password that arrives here unflagged lands in preview and apply logs in cleartext, and in the state bucket readable by anything that can read state. The flag is set by the plugin on InputValue.secret (plugin.proto field 10) and is honoured both on the parent stack root's exports and here, on the in-memory sibling path.
type PluginOwnedBinding ¶
type PluginOwnedBinding struct {
Kind PluginOwnedKind
PluginName string // name under server.yaml's plugins: block
}
PluginOwnedBinding is the record for a single type → plugin association captured by RegisterPluginOwnedType.
func IsPluginOwnedType ¶
func IsPluginOwnedType(name string) (PluginOwnedBinding, bool)
IsPluginOwnedType reports whether name was recorded by RegisterPluginOwnedType and returns the full binding (kind + plugin name). Lookups are case sensitive — plugin type names are matched byte-for-byte.
type PluginOwnedKind ¶
type PluginOwnedKind string
PluginOwnedKind labels which role a plugin-registered type fills so the three Detect call-sites in read.go and the three Prepare*ForDeploy branches in client.go can tell plugin-owned templates from plugin-owned resources/registrars/provisioner-fields.
Populated at parse time by pkg/stackread via RegisterPluginOwnedType — one entry per type each declared plugin's Schema RPC advertises.
const ( PluginOwnedKindResource PluginOwnedKind = "resource" PluginOwnedKindTemplate PluginOwnedKind = "template" PluginOwnedKindRegistrar PluginOwnedKind = "registrar" PluginOwnedKindStateStore PluginOwnedKind = "state-store" PluginOwnedKindSecretsProvider PluginOwnedKind = "secrets-provider" PluginOwnedKindComputeProcessor PluginOwnedKind = "compute-processor" PluginOwnedKindVmDriver PluginOwnedKind = "vm-driver" PluginOwnedKindProvisionerField PluginOwnedKind = "provisioner-field" // PluginOwnedKindAuth labels a `type:` discriminator used in a // server.yaml / secrets.yaml `auth:` block. Deliberately equal to // `PluginOwnedKindResource + "/auth"` — the composite string already // shipped in `plugin_bootstrap.go` for aws/yandex/cloudru entries, so // adding this const + refactoring the three literals is byte-identical // to the existing registration; nothing changes for the five // link-time-imported + bootstrap-table-seeded plugins. // // The const is what `stackread.registerSchemaTypes` passes to // `RegisterPluginOwnedType` for every entry in a plugin's // `SchemaResponse.auth_types`. Kind is read for provenance only; the // state-store/secrets-provider branch at `mapping.go:162` fires on // distinct kinds, so auth seeds `providerConfigMapping` alone (which // is what `DetectAuthProvider` at `read.go:183` reads, and the only // map the auth path touches). PluginOwnedKindAuth PluginOwnedKind = PluginOwnedKindResource + "/auth" )
type PluginPreparedInput ¶
type PluginPreparedInput struct {
// Input is the plugin's typed Input (decoded back into a
// map[string]any by pkg/stackread via scPlugin.InputsToPlain so
// the reflect walker never has to deal with unexported fields the
// plugin's typed struct might have carried).
Input any `yaml:"input,omitempty" json:"input,omitempty"`
// BaseDnsZone_ is the typed Input's api.DnsConfigAware.OverriddenBaseZone.
BaseDnsZone_ string `yaml:"baseDnsZone,omitempty" json:"baseDnsZone,omitempty"`
// Uses_ is the typed Input's api.ResourceAware.Uses.
Uses_ []string `yaml:"uses,omitempty" json:"uses,omitempty"`
// DependsOnResources_ is the typed Input's
// api.WithDependsOnResources.DependsOnResources.
DependsOnResources_ []StackConfigDependencyResource `yaml:"dependsOnResources,omitempty" json:"dependsOnResources,omitempty"`
// Domain_ is the `domain:` the operator declared on the CLIENT stack,
// carried here for the same reason as the three fields above: a
// downstream consumer needs it and must not have to parse the plugin's
// own Input to find it.
//
// The consumer is provisionDomainRegistrar (pkg/clouds/pulumi/
// plugin_sidecars.go), which resolves the registrar for a plugin
// template's zone — core builds registrars lazily, so a zone only the
// plugin publishes in is never sent to it otherwise. It used to read the
// domain out of the descriptor's config, which works while that config is
// the client's `{"stackConfig":{…}}` but NOT for a plugin-owned template,
// where the descriptor carries this struct instead and there is no
// `stackConfig` key anywhere in it. That is why
// forge-landing-ru-apex--staging kept failing with `no yc-dns registrar
// initialised that serves "simple-forge.ru"` even after the probe learned
// the nested-Site spelling: the probe was being handed the wrong object.
//
// Each plugin mirrors the domain somewhere in its own Input under its own
// name (sc-plugin-yandex and sc-plugin-aws both use `siteDomain`), so
// there is no field name core could agree on. This one is core's.
Domain_ string `yaml:"domain,omitempty" json:"domain,omitempty"`
}
PluginPreparedInput wraps a PluginStackConvertResult as a Go value that satisfies DnsConfigAware, ResourceAware, and WithDependsOnResources — the three interfaces SC core type-asserts off clientStackDesc.Config.Config at pkg/clouds/pulumi/deploy.go (lines 133, 146, 153) and pkg/provisioner/unresolved.go (109, 112).
EVERY FIELD MUST BE EXPORTED. SC core walks this struct via reflection in pkg/provisioner/placeholders (applyTemplatesRecursive) for `${X}` placeholder substitution, and that walker calls reflect.Value.Set on every field. A reflect.Set into an unexported field panics with "reflect.Value.Set using value obtained using unexported field" — live-caught on forge-aigateway isolated run 41469779418 (2026-11-02), which panicked before any resource was provisioned and failed every service in the matrix.
Also satisfies the no-op side of each interface for stacks whose plugin response omitted the structured fields (empty []string / nil slice reads as "no constraints" — same as a stack that never declared the attribute).
Note that method NAMES collide with the fields they expose, so the fields have an underscore suffix. The interface methods thunk to the fields and are what Go code sees via type-assertion; the fields are what the placeholders walker sees via reflection.
func NewPluginPreparedInput ¶
func NewPluginPreparedInput(result *PluginStackConvertResult) *PluginPreparedInput
NewPluginPreparedInput wraps a plugin's typed Input + the three structured fields for downstream type-asserts. The pkg/stackread converter calls this after decoding the ConvertStackConfigResponse.
func (*PluginPreparedInput) DependsOnResources ¶
func (p *PluginPreparedInput) DependsOnResources() []StackConfigDependencyResource
DependsOnResources implements WithDependsOnResources.
func (*PluginPreparedInput) MarshalJSON ¶
func (p *PluginPreparedInput) MarshalJSON() ([]byte, error)
MarshalJSON unwraps PluginPreparedInput for the Provision bus. SC core forwards the deploying stack's `Config.Config` across the bus via pkg/clouds/pulumi/plugin_sidecars.go's serializeConfigToInputs, which calls json.Marshal. The plugin's Provision handler decodes the resulting InputValue tree into its typed Input shape (*LambdaInput, *StaticSiteInput, …). Without this method, the serialised shape would be `{input: {...real Input fields...}, baseDnsZone: ..., uses: [...], dependsOnResources: [...]}` — and the plugin's decoder would find every expected Input field at the top level is nil, panic'ing on first dereference. Live-caught on forge-aigateway isolated-stack run 41483738313 (2026-11-02).
Returning just p.Input makes the wire shape identical to what SC core's pre-A2 Prepare*ForDeploy produced: the raw typed Input is what the plugin's Provision handler expects.
SC core's own interface asserts (DnsConfigAware / ResourceAware / WithDependsOnResources) are still answered by the methods above — those read the exported *_ fields, which are preserved on the SC-core-side wrapper. Only the WIRE representation unwraps.
func (*PluginPreparedInput) OverriddenBaseZone ¶
func (p *PluginPreparedInput) OverriddenBaseZone() string
OverriddenBaseZone implements DnsConfigAware.
func (*PluginPreparedInput) StackConfigDomain ¶
func (p *PluginPreparedInput) StackConfigDomain() string
StackConfigDomain returns the client stack's declared domain. Mirrors the OverriddenBaseZone / Uses / DependsOnResources accessors above.
func (*PluginPreparedInput) Uses ¶
func (p *PluginPreparedInput) Uses() []string
Uses implements ResourceAware.
type PluginRequirement ¶
type PluginRequirement struct {
// PluginName is the key operators write under `plugins:` in server.yaml.
// It MUST match the name the plugin itself uses — it's what SC core
// matches against `desc.Plugins[PluginName]`.
PluginName string
// OwnedTypes are the type tokens (resource / registrar / provider /
// state-storage / secrets-provider / compute-processor / template)
// this plugin's /api module registers.
OwnedTypes []string
// DefaultSource is the `source:` block the auto-injector uses when
// an operator's server.yaml references OwnedTypes without declaring
// `plugins.<PluginName>`. Version is left empty — resolved against
// the GitHub releases API at parse time.
DefaultSource PluginSource
}
PluginRequirement names a plugin and the type tokens it owns. Each out-of-tree sc-plugin's `/api` module calls RegisterPluginRequirement at init() time so that SC core — which has already deleted the corresponding in-tree subtree — can detect missing `plugins:` blocks in server.yaml and auto-inject the latest release BEFORE any Pulumi state is touched.
See forge/docs/design/2026-10-24/sc-plugin-architecture/ 04-no-destroy-invariant.md Addendum J.
func LookupPluginRequirement ¶
func LookupPluginRequirement(typeToken string) (PluginRequirement, bool)
LookupPluginRequirement returns the plugin requirement that owns a type token, if any. False when the type is in-tree (or unknown).
type PluginResourceOutput ¶
type PluginResourceOutput struct {
// PluginName is the plugin that owns the resource (e.g. `gcp`).
PluginName string
// Urn is the Pulumi URN the plugin registered the resource under.
Urn string
// Outputs is what the plugin published, keyed exactly as the plugin exported
// it — the same keys that appear on the parent stack root. Values a plugin
// sent in a shape core cannot represent as a plain Go value are absent rather
// than zeroed.
Outputs map[string]PluginOutputValue
}
PluginResourceOutput is what a plugin-owned parent-stack resource leaves on api.ResourceOutput.Ref, so that a SIBLING resource provisioned after it can read what it produced.
Why this type exists: resources that declare WithParentDependencies are provisioned after their dependencies and receive the accumulated `map[string]*ResourceOutput` (see pkg/clouds/pulumi/provision.go). An in-tree resource puts its typed output on `.Ref` and the consumer type-asserts it — that is how a k3s cluster learns its machines' addresses. A plugin-owned resource used to put the bare string `plugin:<name>:<urn>` there, so a sibling learned the URN and nothing else, even though core had just harvested every value the plugin published. Post plugin-extraction most resources are plugin-owned — buckets, databases, registries — which is exactly the set a new sibling dependency wants to read.
String() still renders `plugin:<name>:<urn>` so anything that logged or formatted the old placeholder reads identically. Values are deliberately NOT part of that rendering: some of them are secret.
func PluginOutputsOf ¶
func PluginOutputsOf(outs map[string]*ResourceOutput, resourceName string) (*PluginResourceOutput, error)
PluginOutputsOf resolves a plugin-owned sibling's outputs out of the outputs of the resources provisioned before this one.
`outs` is ProvisionParams.ResourceOutputs. A consumer only receives a sibling in there if its own config implements WithParentDependencies and names that resource — so "not found" almost always means the dependency was never declared, and the error says so rather than reporting an absence.
func (*PluginResourceOutput) Lookup ¶
func (o *PluginResourceOutput) Lookup(key string) (PluginOutputValue, bool)
Lookup returns one published value and whether the plugin published it at all.
func (*PluginResourceOutput) String ¶
func (o *PluginResourceOutput) String() string
String renders the resource the way the pre-typed placeholder did.
Nil-safe because PluginOutputsOf's error paths hand back a nil output alongside the error, and a caller that logs and carries on would otherwise panic inside the logging rather than at the mistake.
func (*PluginResourceOutput) StringOf ¶
func (o *PluginResourceOutput) StringOf(key string) (string, error)
StringOf reads one published value as a string.
The error lists the keys that WERE published, because the realistic failure is not a typo: it is a plugin version that predates the key being asked for, or a resource whose export names are keyed off its own name and so differ per declaration. Without the list, the operator sees "no output X" and has no way to find out what to ask for instead.
type PluginSource ¶
type PluginSource struct {
// Type of the source. v1: "github-release".
Type string `json:"type" yaml:"type"`
// Repository identifier. For github-release: "owner/repo" (e.g.
// "simple-container-com/sc-plugin-cloudflare").
Repository string `json:"repository" yaml:"repository"`
// Version tag — a specific release name. "latest" is NOT supported in
// v1: operators pin a version explicitly so deploys are reproducible.
Version string `json:"version" yaml:"version"`
// BinaryName overrides the default binary filename resolution. Default
// derivation: "sc-plugin-<name>-<goos>-<goarch>[.exe]" where <name> is
// the repo name minus the "sc-plugin-" prefix (e.g.
// simple-container-com/sc-plugin-cloudflare → "sc-plugin-cloudflare").
BinaryName string `json:"binaryName,omitempty" yaml:"binaryName,omitempty"`
}
PluginSource describes where SC should fetch a plugin binary from. Only "github-release" is supported in v1; "oci" is a planned addition (see 03 §6.2).
type PluginSpec ¶
type PluginSpec struct {
// Path to the plugin binary on disk. Mutually exclusive with Source — if
// both are set, Path wins. For dev loops + air-gapped operators.
Path string `json:"path,omitempty" yaml:"path,omitempty"`
// Source resolves to a downloaded + cached binary. Set this for the
// standard operator flow — points at a plugin repo's release.
Source *PluginSource `json:"source,omitempty" yaml:"source,omitempty"`
// SHA256 hex digest of the binary. When set, SC refuses to spawn a
// binary whose hash does not match — the integrity guard from D10.
// For Source-based specs, SC additionally cross-checks against the
// release's sha256sums.txt asset if present. When empty, SC logs a
// WARN but proceeds.
SHA256 string `json:"sha256,omitempty" yaml:"sha256,omitempty"`
}
PluginSpec configures one SC plugin that will be loaded at provision time. Operators give either a local path (dev / air-gapped) or a source block that SC resolves at load time against a GitHub Release.
func (*PluginSpec) Copy ¶
func (s *PluginSpec) Copy() PluginSpec
Copy deep-copies the spec, including the Source pointer — a shared pointer would let one stack's placeholder resolution mutate another's pin.
type PluginStackConvertRequest ¶
type PluginStackConvertRequest struct {
TemplateType string
StackName string
StackDir string
// StackConfig is one of *StackConfigCompose, *StackConfigSingleImage,
// or *StackConfigStatic. stackread marshals it to the proto's
// map<string, InputValue> wire form.
StackConfig any
// TemplateConfig is the parent-side TEMPLATE config body — the raw
// map or typed struct `stackDesc.Config.Config` carries after
// DetectTemplateType ran. For plugin-owned templates it is a raw
// map[string]any (the opaque decoder preserved the YAML tree); the
// plugin decodes it into its own typed TemplateConfig on receipt.
TemplateConfig any
}
PluginStackConvertRequest carries the operator-side state the plugin's existing /api-registered ToXxxConfig closures already consume: the typed StackConfig (compose/single-image/static), the stack name, and the ${git:root}-resolved stackDir. All scalar — no SC-core-side types that cannot cross a gRPC boundary.
type PluginStackConvertResult ¶
type PluginStackConvertResult struct {
// Input is the plugin's typed Input (*LambdaInput /
// *StaticSiteInput / *EcsFargateInput etc.) decoded from the RPC
// response. SC core forwards it verbatim through the Provision RPC
// — the plugin's Provision handler receives the same shape it
// returned here, keeping the end-to-end round-trip stable.
Input any
// BaseDnsZone satisfies DnsConfigAware.OverriddenBaseZone.
BaseDnsZone string
// Uses satisfies ResourceAware.Uses.
Uses []string
// DependsOnResources satisfies WithDependsOnResources.DependsOnResources.
DependsOnResources []StackConfigDependencyResource
}
PluginStackConvertResult mirrors the typed response SC core wraps in pluginPreparedInput. The three downstream interfaces (DnsConfigAware, ResourceAware, WithDependsOnResources) read exactly these fields.
type PluginStackConverter ¶
type PluginStackConverter func(ctx context.Context, pluginName string, req PluginStackConvertRequest) (*PluginStackConvertResult, error)
PluginStackConverter is the injection point SC core's parse-time path uses to turn a plugin-owned template's merged StackConfig* into the plugin's typed Input via the ConvertStackConfig RPC. The dialling code lives in pkg/stackread (which imports pkg/plugin — allowed) and registers itself here with RegisterPluginStackConverter at init-time.
Why a function variable instead of calling pkg/plugin directly: pkg/api cannot import pkg/plugin (pkg/plugin already imports pkg/api — the cycle is why stackread exists as a leaf). The seam keeps pkg/api clean while letting Prepare*ForDeploy branch on plugin-owned types.
type PreviewResult ¶
type PreviewResult struct {
StackName string `json:"stackName" yaml:"stackName"`
Summary string `json:"summary" yaml:"summary"`
Operations map[string]int `json:"operations" yaml:"operations"`
}
func (*PreviewResult) String ¶
func (r *PreviewResult) String() string
type ProvenanceDescriptor ¶
type ProvenanceDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Format string `json:"format,omitempty" yaml:"format,omitempty"` // Default: "slsa-v1.0"
Output *OutputDescriptor `json:"output,omitempty" yaml:"output,omitempty"`
IncludeGit bool `json:"includeGit,omitempty" yaml:"includeGit,omitempty"`
IncludeDocker bool `json:"includeDockerfile,omitempty" yaml:"includeDockerfile,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
Builder *BuilderDescriptor `json:"builder,omitempty" yaml:"builder,omitempty"`
Metadata *MetadataDescriptor `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}
ProvenanceDescriptor configures SLSA provenance
type ProvisionParams ¶
type ProvisionParams struct {
StacksDir string `json:"rootDir" yaml:"rootDir"`
Profile string `json:"profile" yaml:"profile"`
Stacks []string `json:"stacks" yaml:"stacks"`
SkipRefresh bool `json:"skipRefresh" yaml:"skipRefresh"`
SkipPreview bool `json:"skipPreview" yaml:"skipPreview"`
DetailedDiff bool `json:"detailedDiff" yaml:"detailedDiff"` // Enable detailed diff output for granular change visibility
Timeouts Timeouts `json:",inline" yaml:",inline"`
}
type Provisioner ¶
type Provisioner interface {
ProvisionStack(ctx context.Context, cfg *ConfigFile, stack Stack, params ProvisionParams) error
SetPublicKey(pubKey string)
DeployStack(ctx context.Context, cfg *ConfigFile, stack Stack, params DeployParams) error
DestroyChildStack(ctx context.Context, cfg *ConfigFile, stack Stack, params DestroyParams, preview bool) error
PreviewStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params ProvisionParams) (*PreviewResult, error)
PreviewChildStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params DeployParams) (*PreviewResult, error)
OutputsStack(ctx context.Context, cfg *ConfigFile, stack Stack, params StackParams) (*OutputsResult, error)
CancelStack(ctx context.Context, cfg *ConfigFile, stack Stack, params StackParams) error
DestroyParentStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params DestroyParams, preview bool) error
SetConfigReader(ProvisionerFieldConfigReaderFunc)
}
type ProvisionerConfigAware ¶
ProvisionerConfigAware is implemented by the pulumi provisioner's config. Used by ValidatePluginRequirements to reach state-storage and secrets-provider type tokens without importing pkg/clouds/pulumi. Method names use the `Type` suffix to avoid colliding with same-named struct fields on the concrete config.
type ProvisionerDescriptor ¶
type ProvisionerDescriptor struct {
Type string `json:"type" yaml:"type"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
// contains filtered or unexported fields
}
ProvisionerDescriptor describes the provisioner schema
func (*ProvisionerDescriptor) Copy ¶
func (s *ProvisionerDescriptor) Copy() ProvisionerDescriptor
func (*ProvisionerDescriptor) GetProvisioner ¶
func (s *ProvisionerDescriptor) GetProvisioner() Provisioner
func (*ProvisionerDescriptor) SetProvisioner ¶
func (s *ProvisionerDescriptor) SetProvisioner(p Provisioner)
func (*ProvisionerDescriptor) ValuesOnly ¶
func (s *ProvisionerDescriptor) ValuesOnly() ProvisionerDescriptor
ValuesOnly returns copy of descriptor without provisioner reference
type ProvisionerFieldConfigRegister ¶
type ProvisionerFieldConfigRegister map[string]ProvisionerFieldConfigReadFunc
func GetRegisteredProvisionerFieldConfigs ¶
func GetRegisteredProvisionerFieldConfigs() ProvisionerFieldConfigRegister
GetRegisteredProvisionerFieldConfigs returns all registered provisioner field configurations Used by schema generator to automatically discover provisioner resource types
type ProvisionerInitFunc ¶
type ProvisionerInitFunc func(config Config, opts ...ProvisionerOption) (Provisioner, error)
type ProvisionerOption ¶
type ProvisionerOption func(p Provisioner) error
func WithFieldConfigReader ¶
func WithFieldConfigReader(f ProvisionerFieldConfigReaderFunc) ProvisionerOption
type ProvisionerRegisterMap ¶
type ProvisionerRegisterMap map[string]ProvisionerInitFunc
type ReadOpts ¶
type ReadOpts struct {
IgnoreServerMissing bool
IgnoreClientMissing bool
IgnoreSecretsMissing bool
RequireClientConfigs []string
RequireServerConfigs []string
RequireSecretConfigs []string
// PluginTypesNotNeeded lets a read try the cheap server-descriptor parse
// that does NOT pre-spawn every declared plugin to discover its types.
//
// Only for callers that read a stack and then neither provision, deploy,
// nor convert a stack config: the cheap parse does not record plugin specs
// for the ConvertStackConfig dialler, so a conversion afterwards would fail
// with "no plugin spec recorded". `sc stack secret-get` is the model case —
// it reads one value out of secrets.yaml and exits.
//
// It is a HINT, not a promise. The read falls back to the full
// plugin-aware parse whenever the cheap one fails, so a server.yaml whose
// types only a plugin's Schema can describe still works; it just costs
// what it costs today. Nothing becomes unreadable by setting this.
//
// Why it matters (measured 2026-11-09): with the per-version Schema cache
// cold, `sc stack secret-get` spawned sc-plugin-cloudflare and took
// 0.59-1.32 s against 0.06-0.09 s warm — and in CI the cache AND the
// binary are both absent, so the same command downloads a 112 MiB plugin
// release (sc-plugin-cloudflare-linux-amd64 is 117,547,170 bytes) to read
// a string out of a YAML file. forge's own provision.yaml does this three
// times in a row.
PluginTypesNotNeeded bool
}
type RefreshResult ¶
func (*RefreshResult) String ¶
func (r *RefreshResult) String() string
type RegistrarConfig ¶
type RegistrarDescriptor ¶
type RegistrarDescriptor struct {
Type string `json:"type" yaml:"type"`
// Default marks this registrar as the one that handles any domain no other
// registrar claims. At most one registrar in a stack may set it.
//
// It exists because a registrar's declared zone is not the set of zones it can
// serve. A Cloudflare registrar authenticates against a whole account and looks
// up whichever zone the deploying stack asks for via `baseDnsZone`, so its
// `zoneName:` is only a default — the fleet's registrar declares
// `simple-container.com` while every service it publishes sits under
// `simple-forge.com`. With a single registrar that never mattered, because the
// single registrar handled everything. Adding a second one makes routing by zone
// suddenly load-bearing, and without this marker the first two-registrar deploy
// fails on every domain the narrow declaration misses.
//
// Not implicit on purpose: falling back to "whichever registrar sorts first"
// would silently publish a domain through a provider chosen by alphabet.
Default bool `json:"default,omitempty" yaml:"default,omitempty"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func (*RegistrarDescriptor) Copy ¶
func (s *RegistrarDescriptor) Copy() RegistrarDescriptor
func (RegistrarDescriptor) IsConfigured ¶
func (r RegistrarDescriptor) IsConfigured() bool
IsConfigured reports whether the descriptor declares anything at all. A server.yaml with no registrar block yields the zero value, which is legal and means "this stack manages no DNS".
type RegistrarZonesAware ¶
type RegistrarZonesAware interface {
Zones() []string
}
RegistrarZonesAware is implemented by a RegistrarConfig that knows which DNS zones it is authoritative for, so a domain can be routed to the right registrar without having to construct (and therefore authenticate) any of them first. Optional: a registrar config that does not implement it can still be the only registrar in a stack.
type RemoteImage ¶
type ReplaceRule ¶
type ReplaceRule string
ReplaceRule names which exemption a type qualifies under, so a diagnostic can say WHY a replace was let through. The guard itself only needs the boolean.
const ( ReplaceRuleNone ReplaceRule = "" // ReplaceRuleRevision: the old revision survives the replace. ReplaceRuleRevision ReplaceRule = "revision-based" // ReplaceRuleConfigRegenerated: the object is briefly absent, and // its whole content comes from config on every apply. ReplaceRuleConfigRegenerated ReplaceRule = "regenerated-from-config" // ReplaceRuleEngineOnly: the resource exists only in the engine's // state and the replace makes no remote call. ReplaceRuleEngineOnly ReplaceRule = "engine-only" )
func SafeToReplaceRule ¶
func SafeToReplaceRule(resourceType string) ReplaceRule
SafeToReplaceRule reports the rule under which this type is exempt, or ReplaceRuleNone. Checked in rule order: where a type somehow satisfies more than one, the narrower claim is the true one, so the diagnostic never overstates what is known about the replace.
type ReportingDescriptor ¶
type ReportingDescriptor struct {
DefectDojo *DefectDojoDescriptor `json:"defectdojo,omitempty" yaml:"defectdojo,omitempty"`
PRComment *PRCommentDescriptor `json:"prComment,omitempty" yaml:"prComment,omitempty"`
}
ReportingDescriptor configures external reporting and PR comment generation.
type ResourceAware ¶
type ResourceAware interface {
Uses() []string
}
type ResourceDescriptor ¶
type ResourceDescriptor struct {
Type string `json:"type" yaml:"type"`
Name string `json:"name" yaml:"name"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func (*ResourceDescriptor) Copy ¶
func (s *ResourceDescriptor) Copy() ResourceDescriptor
type ResourceInput ¶
type ResourceInput struct {
Descriptor *ResourceDescriptor `json:"descriptor" yaml:"descriptor"`
StackParams *StackParams `json:"deployParams" yaml:"deployParams"`
// ComponentRaw carries the operator-declared `.Raw` map of a Component
// resource when SC core's sidecar wrapper dispatches this input into a
// `deployTo:` template (slice 1a.1 of sc-components-platform; design doc
// §#19 path (b)). The dispatched template's ProvisionFunc checks for a
// non-nil ComponentRaw and overlays the component's fields (image, env,
// ingress, signingKey, …) onto its typed input struct before building
// the cloud resource. nil for non-component dispatches — every existing
// ProvisionFunc on main sees this unset and keeps working. See
// forge/docs/design/2026-11-10/sc-components-platform/README.md §#19 for
// the shape + the memory
// `interface_assertion_against_plugin_owned_value_fails_in_prod` for why
// SC core cannot type-overlay plugin-owned fields itself.
ComponentRaw map[string]any `json:"component_raw,omitempty" yaml:"component_raw,omitempty"`
}
func (*ResourceInput) ToResName ¶
func (r *ResourceInput) ToResName(resName string) string
ToResName adds environment suffix if environment is specified in the resource input
type ResourceOutput ¶
type ResourceOutput struct {
Ref any `json:"ref" yaml:"ref"`
}
type ResourceRef ¶
type ResourceRef struct {
// ResourceName is the sibling resource, named exactly as the `resources:`
// block of server.yaml names it.
ResourceName string
// Key is which of that resource's outputs to read (e.g. `kubeconfig`). The
// set of valid keys belongs to the resource that publishes them, not here.
Key string
}
ResourceRef is a reference from one parent-stack resource's config field to an output of a SIBLING resource — a resource of the same server.yaml, the same stack and the same environment.
Why this exists. A `k3s-cluster` produces the cluster's kubeconfig, and a `kubernetes-caddy` needs a kubeconfig to deploy the edge into that cluster, but the field took a literal string only. So the single most obvious server.yaml anyone would write — a cluster and its front door, side by side — could not be provisioned in one pass. The documented workaround was to provision twice and carry the value across by hand:
- provision with the Caddy resource absent, read the kubeconfig from the stack outputs,
- paste it into `secrets.yaml` and provision again with `kubeconfig: ${secret:K3S_KUBECONFIG}`.
That works, and it is what all three k3s smokes of the 2026-11-08 fleet stand did. As a documented path it is poor in three separate ways: it makes a one-command provision a two-command one, it puts a cluster-admin credential in the operator's hands and in `secrets.yaml` purely as plumbing, and the pasted copy can go stale against the cluster with nothing to notice — a control-plane rebuild or a `tlsSans` change reissues the certificate, and the next deploy fails with an x509 error pointing at the Caddy resource rather than at the stale string. An output only a human can carry between two resources is a missing edge in the dependency graph, not a configuration style.
See forge/docs/roadmap/items/sc-k3s-caddy-needs-literal-kubeconfig.md.
func ParseResourceRef ¶
func ParseResourceRef(value string) (ResourceRef, bool, error)
ParseResourceRef reads the `${resource:<name>.<key>}` form.
Whole-string match, not a substring: a field is either a reference or a literal value. Half a kubeconfig with a reference spliced into it is not a thing anyone means, and treating it as one would turn a typo into a provider built from a corrupt credential.
The boolean is "this is a reference" and the error is "it is a reference and it is malformed" — two different answers, because a literal value that merely starts with a brace must pass through untouched while `${resource:no-dot}` has to be a refusal rather than a string that silently reaches a provider.
func (ResourceRef) String ¶
func (r ResourceRef) String() string
String renders the reference back to the form an operator wrote, so an error message can quote what is in their server.yaml rather than a struct dump.
type ResponseTimeConfig ¶
type ResponseTimeConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
}
type SBOMDescriptor ¶
type SBOMDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Format string `json:"format,omitempty" yaml:"format,omitempty"` // Default: "cyclonedx-json"
Generator string `json:"generator,omitempty" yaml:"generator,omitempty"` // Default: "syft"
Output *OutputDescriptor `json:"output,omitempty" yaml:"output,omitempty"`
Cache *CacheDescriptor `json:"cache,omitempty" yaml:"cache,omitempty"`
Attach *AttachDescriptor `json:"attach,omitempty" yaml:"attach,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
}
SBOMDescriptor configures SBOM generation
type ScanDescriptor ¶
type ScanDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Tools []ScanToolDescriptor `json:"tools,omitempty" yaml:"tools,omitempty"`
FailOn string `json:"failOn,omitempty" yaml:"failOn,omitempty"` // "critical", "high", "medium", "low"
WarnOn string `json:"warnOn,omitempty" yaml:"warnOn,omitempty"` // "critical", "high", "medium", "low"
// SoftFail converts policy violations (failOn threshold exceeded) from hard errors to
// warnings. The scan still runs and results are reported/uploaded, but a policy
// violation never blocks the deployment (exit 0 instead of exit 1).
SoftFail bool `json:"softFail,omitempty" yaml:"softFail,omitempty"`
Output *OutputDescriptor `json:"output,omitempty" yaml:"output,omitempty"`
Cache *CacheDescriptor `json:"cache,omitempty" yaml:"cache,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
}
ScanDescriptor configures vulnerability scanning
type ScanToolDescriptor ¶
type ScanToolDescriptor struct {
Name string `json:"name,omitempty" yaml:"name,omitempty"` // "grype", "trivy"
Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
FailOn string `json:"failOn,omitempty" yaml:"failOn,omitempty"`
WarnOn string `json:"warnOn,omitempty" yaml:"warnOn,omitempty"`
}
ScanToolDescriptor configures a specific scanning tool
type SecretsConfigDescriptor ¶
type SecretsConfigDescriptor struct {
Type string `json:"type" yaml:"type"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func (*SecretsConfigDescriptor) Copy ¶
func (s *SecretsConfigDescriptor) Copy() SecretsConfigDescriptor
type SecretsDescriptor ¶
type SecretsDescriptor struct {
SchemaVersion string `json:"schemaVersion" yaml:"schemaVersion"`
Auth map[string]AuthDescriptor `json:"auth" yaml:"auth"`
Values map[string]string `json:"values" yaml:"values"`
}
SecretsDescriptor describes the secrets schema
func DetectAuthType ¶
func DetectAuthType(descriptor *SecretsDescriptor) (*SecretsDescriptor, error)
func ReadSecretsConfigs ¶
func ReadSecretsConfigs(descriptor *SecretsDescriptor) (*SecretsDescriptor, error)
func ReadSecretsDescriptor ¶
func ReadSecretsDescriptor(path string) (*SecretsDescriptor, error)
func (*SecretsDescriptor) Copy ¶
func (s *SecretsDescriptor) Copy() SecretsDescriptor
type SecretsProviderConfig ¶
type SecretsProviderConfig interface {
AuthConfig
IsProvisionEnabled() bool
KeyUrl() string
}
type SecurityDescriptor ¶
type SecurityDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Signing *SigningDescriptor `json:"signing,omitempty" yaml:"signing,omitempty"`
SBOM *SBOMDescriptor `json:"sbom,omitempty" yaml:"sbom,omitempty"`
Provenance *ProvenanceDescriptor `json:"provenance,omitempty" yaml:"provenance,omitempty"`
Scan *ScanDescriptor `json:"scan,omitempty" yaml:"scan,omitempty"`
Reporting *ReportingDescriptor `json:"reporting,omitempty" yaml:"reporting,omitempty"`
}
SecurityDescriptor defines security configuration for container images This is the API-level representation that maps to pkg/security types
func DefaultSecurityDescriptor ¶
func DefaultSecurityDescriptor() *SecurityDescriptor
DefaultSecurityDescriptor returns a default security descriptor
type ServerDescriptor ¶
type ServerDescriptor struct {
SchemaVersion string `json:"schemaVersion" yaml:"schemaVersion"`
Provisioner ProvisionerDescriptor `json:"provisioner" yaml:"provisioner"`
Secrets SecretsConfigDescriptor `json:"secrets" yaml:"secrets"`
CiCd CiCdDescriptor `json:"cicd" yaml:"cicd"`
Templates map[string]StackDescriptor `json:"templates" yaml:"templates"`
Resources PerStackResourcesDescriptor `json:"resources" yaml:"resources"`
Variables map[string]VariableDescriptor `json:"variables" yaml:"variables"`
// Plugins advertises out-of-tree cloud plugins SC core should spawn and
// route resource dispatch to. Phase 0 Step 4 of sc-plugin-architecture;
// details in forge/docs/design/2026-10-24/sc-plugin-architecture/03-architecture.md.
Plugins map[string]PluginSpec `json:"plugins,omitempty" yaml:"plugins,omitempty"`
}
ServerDescriptor describes the server schema
func DetectCiCdType ¶
func DetectCiCdType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func DetectProvisionerType ¶
func DetectProvisionerType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func DetectResourcesType ¶
func DetectResourcesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func DetectSecretsType ¶
func DetectSecretsType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func DetectTemplatesType ¶
func DetectTemplatesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func ReadServerConfigs ¶
func ReadServerConfigs(descriptor *ServerDescriptor) (*ServerDescriptor, error)
func ReadServerDescriptor ¶
func ReadServerDescriptor(path string) (*ServerDescriptor, error)
func (*ServerDescriptor) Copy ¶
func (sd *ServerDescriptor) Copy() ServerDescriptor
func (*ServerDescriptor) IsStrictSchemaVersion ¶
func (sd *ServerDescriptor) IsStrictSchemaVersion() bool
IsStrictSchemaVersion reports whether the descriptor opts into strict mode (schemaVersion 1.1 or newer). Call sites gate plugin-aware behaviour on this — in strict mode we refuse to auto-inject or guess; in lenient mode (1.0 / empty) we preserve the pre-A3 fallback UX.
func (*ServerDescriptor) ValidateSchemaVersion ¶
func (sd *ServerDescriptor) ValidateSchemaVersion() error
ValidateSchemaVersion rejects a server.yaml carrying an unknown schemaVersion string. Empty is accepted (implicit 1.0). Call this early, before any plugin-aware parse step runs.
func (*ServerDescriptor) ValuesOnly ¶
func (sd *ServerDescriptor) ValuesOnly() *ServerDescriptor
ValuesOnly returns copy of descriptor without additional state (e.g. provisioner reference etc.)
type ServerErrorsConfig ¶
type ServerErrorsConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
}
ALB-specific alert configurations
type SigningDescriptor ¶
type SigningDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
Provider string `json:"provider,omitempty" yaml:"provider,omitempty"` // Default: "sigstore"
Keyless bool `json:"keyless,omitempty" yaml:"keyless,omitempty"` // Default: true
PrivateKey string `json:"privateKey,omitempty" yaml:"privateKey,omitempty"`
PublicKey string `json:"publicKey,omitempty" yaml:"publicKey,omitempty"`
// Password is the cosign private key passphrase.
// json:"-" prevents accidental serialization in debug logs and config dumps.
// yaml tag is preserved because the field is loaded from stack YAML configs.
Password string `json:"-" yaml:"password,omitempty"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
Verify *VerifyDescriptor `json:"verify,omitempty" yaml:"verify,omitempty"`
}
SigningDescriptor configures image signing
type SimpleContainerLBConfig ¶
type SimpleContainerLBConfig struct {
// Https is the DEPRECATED spelling of OriginTls. Still honoured, and means
// exactly the same thing — `originTls` is the name that says what it does.
Https bool `json:"https" yaml:"https"`
// OriginTls is whether the edge serving this stack's site terminates TLS for
// it: whether the generated Caddy site address is `https://<domain>` rather
// than `http://<domain>`. The scheme is not decoration — `https://` is what
// arms Caddy's automatic HTTPS, and therefore ACME, for this site.
//
// Unset means "inherit the edge's default" (the template's `originTls`) and,
// failing that, FALSE: something in front — Cloudflare's proxy, a cloud load
// balancer — terminates TLS and the edge serves plain HTTP. That is the
// fleet's normal arrangement, which is why this defaults off while the vm
// resource's `ingress.originTls` defaults on: there, the machine's Caddy IS
// the front door.
//
// NOT the same decision as the template's `clientTls` (formerly `useSSL`),
// which only governs HSTS and which side owns the HTTP→HTTPS redirect.
//
// Has no effect on the vm path, where origin TLS is a property of the
// machine's one Caddy and belongs to the vm resource (`ingress.originTls`)
// rather than to each site.
OriginTls *bool `json:"originTls,omitempty" yaml:"originTls,omitempty"`
// ExtraHelpers renders one directive per line INSIDE the per-stack
// `reverse_proxy { ... }` block (alongside `header_down`, `import
// handle_server_error`, etc.). Use this for reverse-proxy-subdirective
// configuration: `header_down`, `lb_retries`, `transport`, `header_up`.
ExtraHelpers []string `json:"extraHelpers" yaml:"extraHelpers"`
// SiteExtraHelpers renders one directive per line at the SITE LEVEL,
// AFTER the `reverse_proxy { ... }` block closes (alongside `import
// gzip`, `import hsts`, etc.). Use this for site-level HTTP handlers
// that aren't valid as reverse_proxy subdirectives — `rate_limit`,
// `redir`, top-level matchers, `route` blocks, `respond` on specific
// paths. The two fields are distinct because Caddy's grammar gates
// what's accepted at each scope; mis-placing a directive yields a
// Caddyfile parse error at reload time.
SiteExtraHelpers []string `json:"siteExtraHelpers" yaml:"siteExtraHelpers"`
// RequestBufferSize controls the `request_buffers` directive on the
// generated reverse_proxy block. Bodies up to this size are buffered so
// the upstream receives Content-Length instead of Transfer-Encoding:
// chunked — WSGI frameworks (Django #28668) read an empty body on chunked
// requests. The value is parsed as a byte size (humanize: "512KB",
// "4MiB"), validated (max 16MiB — the buffer is held in edge-proxy memory
// per in-flight request), and rendered as a plain byte count, so no
// user-controlled text reaches the shared Caddyfile. "0" omits the
// directive entirely (also the escape hatch for edges running Caddy
// < 2.6.0, which predates request_buffers). Unset/empty = default 1MiB.
// Chunked bodies LARGER than the buffer still reach the upstream chunked
// and remain subject to Django #28668 — raise the size for endpoints
// receiving large chunked uploads.
RequestBufferSize string `json:"requestBufferSize,omitempty" yaml:"requestBufferSize,omitempty"`
}
func (*SimpleContainerLBConfig) OriginTlsEnabled ¶
func (c *SimpleContainerLBConfig) OriginTlsEnabled(edgeDefault *bool) bool
OriginTlsEnabled reports whether the edge terminates TLS for this stack's site, and therefore whether the site address is rendered `https://` (automatic HTTPS and ACME armed) or `http://`.
Precedence: this stack's `originTls`, then its deprecated `https`, then the edge-wide default from the template, then false. A nil receiver answers the same as an empty block, because a client.yaml with no `lbConfig` at all is the majority case and must not behave differently from one that declares the block and says nothing.
func (*SimpleContainerLBConfig) ValidateTls ¶
func (c *SimpleContainerLBConfig) ValidateTls() error
ValidateTls refuses the one combination of the two spellings that cannot be honoured both ways. Everything else resolves by the documented precedence.
type Stack ¶
type Stack struct {
Name string `json:"name" yaml:"name"`
Secrets SecretsDescriptor `json:"secrets" yaml:"secrets"`
Server ServerDescriptor `json:"server" yaml:"server"`
Client ClientDescriptor `json:"client" yaml:"client"`
}
func (*Stack) ChildStack ¶
func (*Stack) ValuesOnly ¶
type StackClientDescriptor ¶
type StackClientDescriptor struct {
Type string `json:"type" yaml:"type"`
ParentStack string `json:"parent" yaml:"parent"`
ParentEnv string `json:"parentEnv" yaml:"parentEnv"`
Template string `json:"template" yaml:"template"`
Config Config `json:",inline" yaml:",inline"`
}
func ConvertClientConfig ¶
func ConvertClientConfig(clientDesc StackClientDescriptor) (*StackClientDescriptor, error)
func (*StackClientDescriptor) Copy ¶
func (s *StackClientDescriptor) Copy() StackClientDescriptor
type StackConfigCompose ¶
type StackConfigCompose struct {
DockerComposeFile string `json:"dockerComposeFile" yaml:"dockerComposeFile"`
Domain string `json:"domain" yaml:"domain"`
Prefix string `json:"prefix" yaml:"prefix"` // prefix for service under LB (e.g. /<service>) default: empty
ProxyKeepPrefix bool `json:"proxyKeepPrefix" yaml:"proxyKeepPrefix"` // if prefix is specified, whether we need to keep it when proxying to service
DomainProxied *bool `json:"domainProxied" yaml:"domainProxied"`
BaseDnsZone string `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
Uses []string `json:"uses" yaml:"uses"`
Runs []string `json:"runs" yaml:"runs"`
Env map[string]string `json:"env" yaml:"env"`
Secrets map[string]string `json:"secrets" yaml:"secrets"`
Version string `json:"version" yaml:"version"` // only when need to forcefully redeploy (e.g. aws secrets)
Size *StackConfigComposeSize `json:"size,omitempty" yaml:"size,omitempty"`
Scale *StackConfigComposeScale `json:"scale,omitempty" yaml:"scale,omitempty"`
Dependencies []StackConfigDependencyResource `json:"dependencies,omitempty" yaml:"dependencies,omitempty"` // when service wants to use resources from another service
Alerts *AlertsConfig `json:"alerts,omitempty" yaml:"alerts,omitempty"`
TextVolumes *[]TextVolume `json:"textVolumes" yaml:"textVolumes"` // extra text volumes to mount to containers (e.g. for k8s deployments)
Headers *Headers `json:"headers" yaml:"headers"` // extra headers to add when serving requests
LBConfig *SimpleContainerLBConfig `json:"lbConfig" yaml:"lbConfig"` // load balancer configuration (so far only applicable for k8s deployments)
CloudExtras *any `json:"cloudExtras" yaml:"cloudExtras"` // when need to specify additional extra config for the specific cloud (e.g. AWS extra roles)
StaticEgressIP *bool `json:"staticEgressIP" yaml:"staticEgressIP"` // when need to provision NAT with fixed egress IP address (e.g. AWS Lambda with static IP)
ImagePullPolicy *string `json:"imagePullPolicy" yaml:"imagePullPolicy"` // applicable only for certain compute types, e.g. Kubernetes
ClusterIPAddress *string `json:"clusterIPAddress" yaml:"clusterIPAddress"` // applicable only for certain compute types, e.g. Kubernetes
Security *SecurityDescriptor `json:"security,omitempty" yaml:"security,omitempty"` // container image security configuration
}
func (*StackConfigCompose) Copy ¶
func (s *StackConfigCompose) Copy() any
type StackConfigComposeScale ¶
type StackConfigComposeScale struct {
Min int `yaml:"min" json:"min"`
Max int `yaml:"max" json:"max"`
Policy *StackConfigComposeScalePolicy `json:"policy" yaml:"policy"`
}
type StackConfigComposeScaleCpu ¶
type StackConfigComposeScaleCpu struct {
Max int `yaml:"max" json:"max"`
}
type StackConfigComposeScaleMemory ¶
type StackConfigComposeScaleMemory struct {
Max int `yaml:"max" json:"max"`
}
type StackConfigComposeScalePolicy ¶
type StackConfigComposeScalePolicy struct {
Cpu *StackConfigComposeScaleCpu `yaml:"cpu" json:"cpu"`
Memory *StackConfigComposeScaleMemory `yaml:"memory" json:"memory"`
}
type StackConfigComposeSize ¶
type StackConfigComposeSize struct {
Name string `yaml:"name" json:"name"`
Cpu string `yaml:"cpu" json:"cpu"`
Memory string `yaml:"memory" json:"memory"`
Ephemeral string `yaml:"ephemeral" json:"ephemeral"`
Requests *StackConfigComposeResources `yaml:"requests,omitempty" json:"requests,omitempty"`
Limits *StackConfigComposeResources `yaml:"limits,omitempty" json:"limits,omitempty"`
}
type StackConfigDependencyResource ¶
type StackConfigDependencyResource struct {
Name string `json:"name" yaml:"name"`
Owner string `json:"owner" yaml:"owner"`
Resource string `json:"resource" yaml:"resource"`
Env *string `json:"env" yaml:"env"`
}
StackConfigDependencyResource when stack depends on resource context of another stack (client configuration)
type StackConfigSingleImage ¶
type StackConfigSingleImage struct {
Image *ContainerImage `json:"image" yaml:"image"`
Domain string `json:"domain" yaml:"domain"`
// DomainProxied mirrors StackConfigCompose.DomainProxied, which is where every
// target actually reads it from (vm-compose, gke-autopilot, kubernetes). Without
// it here the key parses and is then dropped on the floor by the single-image →
// compose conversion: no error, no warning, and an UNPROXIED record pointing at a
// fleet whose origin is deliberately plain HTTP. Live-caught 2026-11-08 on the
// 3-VPS compose smoke, where `domainProxied: true` produced three `proxied=false`
// A records and a name reachable only over cleartext.
DomainProxied *bool `json:"domainProxied" yaml:"domainProxied"`
BaseDnsZone string `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
Env map[string]string `json:"env" yaml:"env"`
Secrets map[string]string `json:"secrets" yaml:"secrets"`
Min int `yaml:"min" json:"min"`
Max int `yaml:"max" json:"max"`
Version string `json:"version" yaml:"version"` // only when need to forcefully redeploy (e.g. aws secrets)
Timeout *int `json:"timeout" yaml:"timeout"`
BasePath string `json:"basePath" yaml:"basePath"` // base path where API will listen on (e.g. for aws apigateway -> lambda integration)
MaxMemory *int `json:"maxMemory" yaml:"maxMemory"` // max memory to use for container
MaxEphemeralStorage *int `json:"maxEphemeralStorage" yaml:"maxEphemeralStorage"` // max ephemeral storage in MB
Uses []string `json:"uses" yaml:"uses"`
StaticEgressIP *bool `json:"staticEgressIP" yaml:"staticEgressIP"` // when need to provision NAT with fixed egress IP address (e.g. AWS Lambda with static IP)
CloudExtras *any `json:"cloudExtras" yaml:"cloudExtras"` // when need to specify additional extra config for the specific cloud (e.g. AWS extra roles)
Dependencies []StackConfigDependencyResource `json:"dependencies,omitempty" yaml:"dependencies,omitempty"` // when service wants to use resources from another service
Security *SecurityDescriptor `json:"security,omitempty" yaml:"security,omitempty"` // container image security configuration
}
type StackConfigStatic ¶
type StackConfigStatic struct {
BundleDir string `json:"bundleDir" yaml:"bundleDir"`
Site StaticSiteConfig `json:",inline" yaml:",inline"`
BucketName string `json:"bucketName" yaml:"bucketName"` // if necessary to override bucket name, only applicable in some clouds (e.g. gcp)
Location string `json:"location" yaml:"location"`
}
type StackDescriptor ¶
type StackDescriptor struct {
Type string `json:"type" yaml:"type"`
ParentStack string `json:"parentStack" yaml:"parentStack"`
Config `json:",inline" yaml:",inline"`
Inherit `json:",inline" yaml:",inline"`
}
func DetectTemplateType ¶
func DetectTemplateType(tpl StackDescriptor) (*StackDescriptor, error)
func PrepareClientConfigForDeploy ¶
func PrepareClientConfigForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientDesc StackClientDescriptor) (*StackDescriptor, error)
func PrepareCloudComposeForDeploy ¶
func PrepareCloudComposeForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigCompose, parentStack string) (*StackDescriptor, error)
func PrepareCloudSingleImageForDeploy ¶
func PrepareCloudSingleImageForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigSingleImage, parentStack string) (*StackDescriptor, error)
func PrepareStaticForDeploy ¶
func PrepareStaticForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigStatic, parentStack string) (*StackDescriptor, error)
func (*StackDescriptor) Copy ¶
func (s *StackDescriptor) Copy() StackDescriptor
type StackParams ¶
type StackParams struct {
StacksDir string `json:"stacksDir" yaml:"stacksDir"`
StackDir string `json:"stackDir" yaml:"stackDir"`
Profile string `json:"profile" yaml:"profile"`
StackName string `json:"stack" yaml:"stack"`
Environment string `json:"environment" yaml:"environment"`
ParentEnv string `json:"parentEnv" yaml:"parentEnv"`
SkipRefresh bool `json:"skipRefresh" yaml:"skipRefresh"`
SkipPreview bool `json:"skipPreview" yaml:"skipPreview"`
DetailedDiff bool `json:"detailedDiff" yaml:"detailedDiff"` // Enable detailed diff output for granular change visibility
Version string `json:"version" yaml:"version"`
Timeouts Timeouts `json:",inline" yaml:",inline"`
Parent bool `json:"parent" yaml:"parent"`
}
func (*StackParams) CopyForParentEnv ¶
func (p *StackParams) CopyForParentEnv(env string) *StackParams
func (*StackParams) ToProvisionParams ¶
func (p *StackParams) ToProvisionParams() ProvisionParams
type StacksMap ¶
func (*StacksMap) ReconcileForDeploy ¶
func (m *StacksMap) ReconcileForDeploy(params StackParams) (*StacksMap, error)
func (*StacksMap) ResolveInheritance ¶
type StateStorageConfig ¶
type StateStorageConfig interface {
AuthConfig
StorageUrl() string
IsProvisionEnabled() bool
}
type StaticSiteConfig ¶
type StaticSiteConfig struct {
Domain string `json:"domain" yaml:"domain"`
BaseDnsZone string `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
IndexDocument string `json:"indexDocument" yaml:"indexDocument"`
ErrorDocument string `json:"errorDocument" yaml:"errorDocument"`
ProvisionWwwDomain bool `json:"provisionWwwDomain" yaml:"provisionWwwDomain"`
CorsConfig *CorsConfig `json:"corsConfig,omitempty" yaml:"corsConfig,omitempty"`
}
type TelegramCfg ¶
type TextVolume ¶
type ToCloudSingleImageConvertFunc ¶
type ToCloudSingleImageConvertFunc func(tpl any, stackCfg *StackConfigSingleImage) (any, error)
type ToCloudStaticSiteConvertFunc ¶
type ToCloudStaticSiteConvertFunc func(tpl any, rootDir, stackName string, stackCfg *StackConfigStatic) (any, error)
type UnhealthyHostsConfig ¶
type UnhealthyHostsConfig struct {
CommonAlertConfig `json:",inline" yaml:",inline"`
}
type UpdateResult ¶
type UpdateResult struct {
StackName string `json:"stackName" yaml:"stackName"`
Summary string `json:"summary" yaml:"summary"`
Operations map[string]int `json:"operations" yaml:"operations"`
}
func (*UpdateResult) String ¶
func (r *UpdateResult) String() string
type VariableDescriptor ¶
type VariableDescriptor struct {
Type string `json:"type" yaml:"type"`
Value string `json:"value" yaml:"value"`
}
func (*VariableDescriptor) Copy ¶
func (s *VariableDescriptor) Copy() VariableDescriptor
type VariableValues ¶
type VerifyDescriptor ¶
type VerifyDescriptor struct {
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
OIDCIssuer string `json:"oidcIssuer,omitempty" yaml:"oidcIssuer,omitempty"`
IdentityRegexp string `json:"identityRegexp,omitempty" yaml:"identityRegexp,omitempty"`
}
VerifyDescriptor configures signature verification
type VmConfigAware ¶
type VmConfigAware interface {
DriverType() string
}
VmConfigAware is implemented by `pkg/clouds/vm.VmConfig`. Used by ValidatePluginRequirements to walk a `type: vm` resource's `provider:` field, which selects a driver that itself can be plugin-owned (`cloudru-evolution-vm`, future `mws-vm`, `selectel-vm`, …). Without this hook the walker only sees `res.Type == "vm"` and misses the plugin that owns the actual driver.
Method is named `DriverType` rather than `Driver` because VmConfig already has a `Driver string` field — same reason StateStorageType is not named StateStorage.
type WithDependencyProviders ¶
type WithDependencyProviders interface {
DependencyProviders() map[string]AuthDescriptor
}
WithDependencyProviders defines configurations where extra cloud providers are required
type WithDependsOnResources ¶
type WithDependsOnResources interface {
DependsOnResources() []StackConfigDependencyResource
}
type WithParentDependencies ¶
type WithParentDependencies interface {
DependsOnResources() []ParentResourceDependency
}
type WithProviderType ¶
type WithProviderType interface {
ProviderType() string
}
WithProviderType defines configuration with specific cloud provider type
Source Files
¶
- alerts.go
- client.go
- cloud_helpers.go
- component_config.go
- component_validation.go
- config.go
- copy.go
- dns.go
- image_build_config.go
- mapping.go
- models.go
- plugin_bootstrap.go
- plugin_converter.go
- plugin_converter_errors.go
- plugin_requirements.go
- plugin_resource_output.go
- read.go
- resource_ref.go
- safe_to_replace.go
- secrets.go
- security_config.go
- server.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package inlinetag detects struct fields that are tagged `json:",inline"` while being NAMED rather than embedded — a shape that means two different things to the two codecs this repo's config travels through, and the single root cause behind seven production failures across the fleet on 2026-11-09.
|
Package inlinetag detects struct fields that are tagged `json:",inline"` while being NAMED rather than embedded — a shape that means two different things to the two codecs this repo's config travels through, and the single root cause behind seven production failures across the fleet on 2026-11-09. |
|
scoped
Package scoped implements the additive per-scope secret store (secrets.<scope>.yaml): committed-encrypted files whose values are sealed to a per-scope recipient set, so a pull_request-triggered CI job can be given a key that opens only the "pr" scope rather than the whole-file store.
|
Package scoped implements the additive per-scope secret store (secrets.<scope>.yaml): committed-encrypted files whose values are sealed to a per-scope recipient set, so a pull_request-triggered CI job can be given a key that opens only the "pr" scope rather than the whole-file store. |