Help us shape the future of Go! Take the 2026 Go Developer Survey

v1

package
v0.6.0 Latest Latest
Warning

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

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

Documentation

Overview

Package crypto contains APIs for configuring short-lived cryptographic material used to communicate with external services, which is mostly based on ServiceAccount annotations. The package parses and validates the annotations alongside legacy fields sourced from other places, like .spec and ConfigMaps.

Index

Constants

View Source
const (
	// GroupAuth is the API group for authentication-related annotations.
	GroupAuth = "auth." + GroupCore

	// GroupMTLS is the API group for mTLS-related annotations.
	GroupMTLS = "mtls." + GroupCore
)

Level 1 groups.

View Source
const (
	// GroupAuthCredential is the API group for credential-related annotations.
	GroupAuthCredential = "credential." + GroupAuth

	// GroupAuthTransitEngine is the API group for transit engine-related annotations.
	GroupAuthTransitEngine = "transit-engine." + GroupAuth

	// GroupAuthAWS is the API group for AWS-related authentication annotations.
	GroupAuthAWS = "aws." + GroupAuth

	// GroupAuthGCP is the API group for GCP-related authentication annotations.
	GroupAuthGCP = "gcp." + GroupAuth

	// GroupAuthDockerHub is the API group for Docker Hub-related authentication annotations.
	GroupAuthDockerHub = "dockerhub." + GroupAuth
)

Level 2 groups (auth).

View Source
const (
	// GroupAWSEKS is the API group for AWS EKS-related annotations.
	GroupAWSEKS = "eks.amazonaws.com"

	// GroupAzureWorkloadIdentity is the API group for Azure Workload Identity-related annotations.
	GroupAzureWorkloadIdentity = "azure.workload.identity"

	// GroupGKEIAM is the API group for GKE IAM-related annotations.
	GroupGKEIAM = "iam.gke.io"
)

Groups borrowed from the cloud providers for UX consistency with the managed Kubernetes services.

View Source
const (
	// ProviderAWS is the AWS service provider.
	ProviderAWS = "aws"

	// ProviderAzure is the Azure service provider.
	ProviderAzure = "azure"

	// ProviderGCP is the GCP service provider.
	ProviderGCP = "gcp"

	// ProviderDockerHub is the Docker Hub service provider.
	ProviderDockerHub = "dockerhub"

	// ProviderGeneric is the service provider for opensource services that
	// accept OIDC tokens directly, using short-lived cryptographic material.
	ProviderGeneric = "generic"

	// ProviderGitHub is the GitHub service provider.
	ProviderGitHub = "github"
)

Service provider names.

View Source
const (
	// CredentialProviderKubernetes is the credential provider that uses the
	// Kubernetes TokenRequest API for acquiring the credential.
	CredentialProviderKubernetes = "kubernetes"

	// CredentialProviderSPIFFE is the credential provider that uses the
	// SPIFFE Broker API for acquiring the credential.
	CredentialProviderSPIFFE = "spiffe"

	// CredentialProviderActionsOIDC is the credential provider that uses the
	// Github/Forgejo Actions OIDC token endpoint for acquiring the credential.
	CredentialProviderActionsOIDC = "actionsoidc"
)

Credential provider values.

View Source
const (
	// CredentialTypeJWT is the credential type for JSON Web Tokens.
	CredentialTypeJWT = "jwt"

	// CredentialTypeX509 is the credential type for X.509 certificates. It is
	// supported only by the `aws` and `gcp` service providers.
	CredentialTypeX509 = "x509"
)

Credential type values.

View Source
const (
	// AnnotationCredentialProvider specifies the provider that issues the
	// credential. It must be one of `kubernetes` or `spiffe`.
	AnnotationCredentialProvider = GroupAuthCredential + "/provider"

	// AnnotationCredentialType specifies the type of the credential.
	// It must be one of `jwt` or `x509`. The `x509` type is supported only by
	// the `aws` and `gcp` service providers.
	AnnotationCredentialType = GroupAuthCredential + "/type"

	// AnnotationCredentialExpiration specifies the requested expiration time
	// of the credential as a Go duration string, e.g. `10m` for ten minutes
	// or `1h` for one hour. The minimum is 10m, the lower bound enforced by the
	// Kubernetes TokenRequest API. It is supported only by the `kubernetes`
	// credential provider and is only used for pre-exchange credentials, as we
	// usually have no control over the expiration for exchanged credentials
	// (the ones we receive from the exchange).
	AnnotationCredentialExpiration = GroupAuthCredential + "/expiration"

	// AnnotationCredentialAudiences specifies the target audiences of the
	// credential. The value is split on line breaks and commas, leading and
	// trailing whitespace is trimmed and empty entries are dropped. It is
	// supported only by the `jwt` credential type. Note: this annotation
	// is ignored when using GKE Workload Identity.
	AnnotationCredentialAudiences = GroupAuthCredential + "/audiences"

	// AnnotationCredentialUsername specifies an optional username to use when
	// authenticating with the service.
	AnnotationCredentialUsername = GroupAuthCredential + "/username"
)

Credential annotation keys.

View Source
const (
	// AnnotationTransitEngineLoginPath specifies the HTTP path in the transit
	// engine where the request for login must be sent, e.g. `auth/jwt/login`.
	AnnotationTransitEngineLoginPath = GroupAuthTransitEngine + "/login-path"

	// AnnotationTransitEngineRole specifies the role to be used when
	// authenticating against the transit engine.
	AnnotationTransitEngineRole = GroupAuthTransitEngine + "/role"
)

Transit engine annotation keys.

View Source
const (
	// AnnotationMTLSSPIFFEServerIDs opts a ServiceAccount into using SPIFFE mTLS
	// and specifies the server SPIFFE IDs to authorize. The value is split on
	// line breaks and commas, leading and trailing whitespace is trimmed and
	// empty entries are dropped. Each entry can be one of:
	//
	//   - `spiffe://<trust domain>` as a SPIFFE Trust Domain.
	//   - `spiffe://<trust domain>/<path>` as an exact SPIFFE ID.
	//   - `spiffe://<trust domain>/<prefix>/` as a SPIFFE ID prefix.
	//     The trailing slash identifies a prefix.
	//   - `spiffe://self` as a symbol for the SPIFFE Trust Domain of our own X509-SVID.
	//   - `spiffe://self/<path>` as an exact SPIFFE ID in the trust domain of
	//     our own X509-SVID.
	//   - `spiffe://self/<prefix>/` as a SPIFFE ID prefix in the trust
	//     domain of our own X509-SVID.
	AnnotationMTLSSPIFFEServerIDs = GroupMTLSSPIFFE + "/server-ids"

	// SPIFFETrustDomainSelf is a symbol for the SPIFFE Trust Domain of our own
	// X509-SVID.
	SPIFFETrustDomainSelf = "self"
)

mTLS annotation keys.

View Source
const (
	// AnnotationAWSSTSEndpoint specifies the AWS STS endpoint for the
	// ServiceAccount.
	AnnotationAWSSTSEndpoint = GroupAuthAWS + "/sts-endpoint"

	// AnnotationEKSRoleARN specifies the AWS IAM Role ARN for the ServiceAccount.
	AnnotationEKSRoleARN = GroupAWSEKS + "/role-arn"
)

AWS annotation keys.

View Source
const (
	// AnnotationGCPWorkloadIdentityProvider specifies the GCP Workload Identity
	// Provider for the ServiceAccount.
	AnnotationGCPWorkloadIdentityProvider = GroupAuthGCP + "/workload-identity-provider"

	// AnnotationGCPServiceAccount specifies the GCP Service Account email for
	// the ServiceAccount.
	AnnotationGCPServiceAccount = GroupGKEIAM + "/gcp-service-account"
)

GCP annotation keys.

View Source
const (
	// AnnotationAzureTenantID specifies the Microsoft Entra tenant ID for the
	// ServiceAccount.
	AnnotationAzureTenantID = GroupAzureWorkloadIdentity + "/tenant-id"

	// AnnotationAzureClientID specifies the Microsoft Entra client ID for the
	// ServiceAccount.
	AnnotationAzureClientID = GroupAzureWorkloadIdentity + "/client-id"
)

Azure annotation keys.

View Source
const (
	// DefaultAudienceAWS is the default audience of the OIDC tokens exchanged
	// for AWS STS credentials.
	DefaultAudienceAWS = "sts.amazonaws.com"

	// DefaultAudienceAzure is the default audience of the OIDC tokens exchanged
	// for Azure credentials.
	DefaultAudienceAzure = "api://AzureADTokenExchange"
)

Default audiences of the OIDC tokens that are exchanged for cloud provider credentials. These are part of the Flux API surface: changing them changes the audience of the issued tokens and is a breaking change.

View Source
const (
	// RegistryPatternAWS is the regex pattern for validating AWS ECR registry
	// hosts. The pattern is anchored so that it matches the registry host in
	// full rather than any substring of it, which is what makes a match proof
	// that the host belongs to ECR. The second capture group is the region.
	RegistryPatternAWS = `` /* 206-byte string literal not displayed */

	// RegistryPatternGCP is the regex pattern for validating GCP Artifact
	// Registry hosts. The docker.s3nsregistry.fr host is the S3NS sovereign
	// cloud artifact registry, which unlike regular GCP Artifact Registry has
	// no location prefix.
	RegistryPatternGCP = `^(((.+\.)?gcr\.io)|(.+-docker\.pkg\.dev)|(docker\.s3nsregistry\.fr))$`

	// RegistryPatternAzure is the regex pattern for validating Azure Container
	// Registry hosts.
	RegistryPatternAzure = `^.+\.(azurecr\.io|azurecr\.cn|azurecr\.de|azurecr\.us)$`
)

Artifact registry host patterns.

View Source
const (
	// ClusterPatternAWS is the regex pattern for validating AWS cluster resource names.
	ClusterPatternAWS = `^arn:aws[\w-]*:eks:([^:]{1,100}):[0-9]{1,30}:cluster/(.{1,200})$`

	// ClusterPatternAzure is the regex pattern for validating Azure cluster resource names.
	ClusterPatternAzure = `` /* 128-byte string literal not displayed */

	// ClusterPatternGCP is the regex pattern for validating GCP cluster resource names.
	ClusterPatternGCP = `^projects/[^/]{1,200}/locations/[^/]{1,200}/clusters/[^/]{1,200}$`
)

Cluster resource name patterns.

View Source
const (
	// RegistryAWSPublicECR is the public AWS ECR registry hostname, reachable
	// over an IPv4-only hostname.
	RegistryAWSPublicECR = "public.ecr.aws"

	// RegistryAWSPublicECRDualStack is the public AWS ECR registry hostname,
	// reachable over a dual-stack hostname.
	RegistryAWSPublicECRDualStack = "ecr-public.aws.com"
)

AWS public ECR registry hostnames.

View Source
const (
	// AnnotationDockerHubOIDCConnectionID specifies the Docker Hub OIDC
	// connection ID for the ServiceAccount.
	AnnotationDockerHubOIDCConnectionID = GroupAuthDockerHub + "/oidc-connection-id"
)

Docker Hub annotation keys.

View Source
const (
	// GroupCore is the core API group for Flux.
	GroupCore = "fluxcd.io"
)

Top-level group.

View Source
const (
	// GroupMTLSSPIFFE is the API group for SPIFFE-related mTLS annotations.
	GroupMTLSSPIFFE = "spiffe." + GroupMTLS
)

Level 2 groups (mtls).

Variables

This section is empty.

Functions

func GetAWSRegionFromArtifactRegistryInput added in v0.5.0

func GetAWSRegionFromArtifactRegistryInput(registryInput string) string

GetAWSRegionFromArtifactRegistryInput returns the AWS region for the given artifact registry input returned by ParseArtifactRepository. The public ECR registry always uses the us-east-1 region.

https://docs.aws.amazon.com/AmazonECR/latest/public/public-registry-auth.html#public-registry-auth-token

func GetAWSRegionFromCodeCommitURL added in v0.5.0

func GetAWSRegionFromCodeCommitURL(gitURL string) (string, error)

GetAWSRegionFromCodeCommitURL returns the AWS region of the given AWS CodeCommit HTTPS Git repository URL, e.g. `us-east-1` for `https://git-codecommit.us-east-1.amazonaws.com/v1/repos/repo`.

https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-git

func GetAWSRoleSessionName added in v0.5.0

func GetAWSRoleSessionName(sa, ns, region string) string

GetAWSRoleSessionName returns the AWS IAM Role session name for the given ServiceAccount and region. It has the following format:

`<serviceaccount>.<namespace>.<region>.fluxcd.io`

func GetDefaultAudienceGCP added in v0.5.0

func GetDefaultAudienceGCP(workloadIdentityProvider string) string

GetDefaultAudienceGCP returns the default audience for the OIDC token that is exchanged for GCP credentials when workload identity federation is configured with the given workload identity provider:

`https://iam.googleapis.com/<workloadIdentityProvider>`

It is the audience used when the credential audiences option is not set. Reference:

https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc_1

func GetRegistryFromArtifactRepository added in v0.5.0

func GetRegistryFromArtifactRepository(artifactRepository string) (string, error)

GetRegistryFromArtifactRepository returns the registry host of the given artifact repository, i.e. of an OCI repository URL or an image reference.

func ParseArtifactRepository added in v0.5.0

func ParseArtifactRepository(serviceProvider, artifactRepository string) (string, error)

ParseArtifactRepository validates the given artifact repository against the rules of the given service provider and returns the provider-specific input required to issue credentials for it. The input is also used as part of the credentials cache key.

For the `aws` service provider the input is the ECR region, unless the registry is the public ECR, in which case it is RegistryAWSPublicECR. For the `gcp` service provider the input is the service provider name, as GCP credentials are not bound to the registry. For the `azure` service provider the input is the ACR registry host.

func ParseClusterAddress added in v0.5.0

func ParseClusterAddress(address string) (string, error)

ParseClusterAddress returns the canonical form https://<lowercase(host)>:<port> of the given Kubernetes API server address. The address is prefixed with https:// when no scheme is present, and the port defaults to 443.

func ParseGitRepository added in v0.5.0

func ParseGitRepository(serviceProvider, gitURL string) (string, error)

ParseGitRepository validates the given Git repository URL against the rules of the given service provider and returns the provider-specific input required to issue credentials for it. The input is also used as part of the credentials cache key.

For the `aws` service provider the input is the Git repository URL, as AWS CodeCommit credentials are a SigV4 signature over the request URL. For the `azure` service provider the input is a constant, as Azure DevOps access tokens are not bound to the Git repository URL.

Types

type AWSClusterSpec added in v0.5.0

type AWSClusterSpec struct {
	// Region is the AWS region.
	Region string
	// Name is the cluster name.
	Name string
}

AWSClusterSpec is the parsed kubeconfig cluster resource name for AWS.

type AWSSpec added in v0.5.0

type AWSSpec struct {
	// RoleARN is the AWS IAM Role ARN.
	RoleARN string
	// STSEndpoint is the resolved AWS STS endpoint.
	STSEndpoint string
	// Cluster is the parsed kubeconfig cluster resource name.
	Cluster *AWSClusterSpec
}

AWSSpec is the validated service-provider-specific specification for AWS.

type AuthSpec added in v0.5.0

type AuthSpec struct {
	// Credential is the credential acquisition specification. It is nil when
	// the ServiceAccount did not opt into object-level workload identity and no
	// legacy audiences are configured.
	Credential *CredentialSpec

	// Transit engine (SOPS).
	TransitEngine *TransitEngineSpec

	// AWS is the AWS specification, when the service provider is `aws`.
	AWS *AWSSpec
	// Azure is the Azure specification, when the service provider is `azure`.
	Azure *AzureSpec
	// GCP is the GCP specification, when the service provider is `gcp`.
	GCP *GCPSpec
	// DockerHub is the Docker Hub specification, when the service provider is
	// `dockerhub`.
	DockerHub *DockerHubSpec
}

AuthSpec is the validated authentication specification.

func (*AuthSpec) OptedIn added in v0.5.0

func (a *AuthSpec) OptedIn() bool

OptedIn reports whether the ServiceAccount explicitly opted into object-level workload identity with the `/provider` and `/type` annotations.

type AzureClusterSpec added in v0.5.0

type AzureClusterSpec struct {
	// SubscriptionID is the subscription ID.
	SubscriptionID string
	// ResourceGroup is the resource group.
	ResourceGroup string
	// Name is the cluster name.
	Name string
}

AzureClusterSpec is the parsed kubeconfig cluster resource name for Azure.

type AzureSpec added in v0.5.0

type AzureSpec struct {
	// TenantID is the Microsoft Entra tenant ID.
	TenantID string
	// ClientID is the Microsoft Entra client ID.
	ClientID string
	// Cluster is the parsed kubeconfig cluster resource name.
	Cluster *AzureClusterSpec
}

AzureSpec is the validated service-provider-specific specification for Azure.

type CredentialSpec added in v0.5.0

type CredentialSpec struct {
	// Provider is the credential provider, one of `kubernetes` or `spiffe`. It
	// is empty when the ServiceAccount did not opt into object-level workload
	// identity with the `/provider` and `/type` annotations.
	Provider string
	// Type is the credential type, one of `jwt` or `x509`. The `x509` type is
	// supported only by the `aws` and `gcp` service providers. It is empty when
	// the ServiceAccount did not opt into object-level workload identity with
	// the `/provider` and `/type` annotations.
	Type string
	// Expiration is the requested credential expiration.
	Expiration time.Duration
	// Audiences are the target audiences of the credential.
	Audiences []string
	// Username is the optional username to authenticate with the service.
	Username string
}

CredentialSpec is the validated credential acquisition specification.

type DockerHubSpec added in v0.5.0

type DockerHubSpec struct {
	// OIDCConnectionID is the Docker Hub OIDC connection ID.
	OIDCConnectionID string
}

DockerHubSpec is the validated service-provider-specific specification for Docker Hub.

type GCPSpec added in v0.5.0

type GCPSpec struct {
	// WorkloadIdentityProvider is the GCP Workload Identity Provider.
	WorkloadIdentityProvider string
	// ServiceAccount is the GCP Service Account email.
	ServiceAccount string
}

GCPSpec is the validated service-provider-specific specification for GCP.

type MTLSSPIFFESpec added in v0.5.0

type MTLSSPIFFESpec struct {
	// ServerIDs are the authorized SPIFFE IDs, prefixes or trust domains of
	// the servers.
	ServerIDs []SPIFFEPeerAuthorization
}

MTLSSPIFFESpec is the validated SPIFFE mTLS specification.

type MTLSSpec added in v0.5.0

type MTLSSpec struct {
	// SPIFFE is the SPIFFE mTLS specification.
	SPIFFE *MTLSSPIFFESpec
}

MTLSSpec is the validated mTLS specification.

type Option added in v0.5.0

type Option func(*options)

Option is a functional option for BuildSpec. The options struct and its fields are intentionally unexported.

func WithAnnotations added in v0.5.0

func WithAnnotations(annotations map[string]string) Option

WithAnnotations sets the ServiceAccount annotations.

func WithCertSecretRef added in v0.5.0

func WithCertSecretRef() Option

WithCertSecretRef indicates that `.spec.certSecretRef` is set.

func WithGitHubEnterpriseServer added in v0.5.0

func WithGitHubEnterpriseServer() Option

WithGitHubEnterpriseServer indicates that the `github` service provider is a GitHub Enterprise Server rather than GitHub.com. It has no effect for any other service provider.

func WithImagePullSecrets added in v0.5.0

func WithImagePullSecrets() Option

WithImagePullSecrets indicates that the ServiceAccount has `.imagePullSecrets`.

func WithKubeConfigAudiences added in v0.5.0

func WithKubeConfigAudiences(audiences string) Option

WithKubeConfigAudiences sets the value of the legacy `audiences` key of the kubeconfig ConfigMap, when present.

func WithKubeConfigCluster added in v0.5.0

func WithKubeConfigCluster(cluster string) Option

WithKubeConfigCluster sets the value of the `cluster` key of the kubeconfig ConfigMap, when present.

func WithOCI added in v0.5.0

func WithOCI() Option

WithOCI indicates that the Flux object talks to an OCI registry.

func WithSOPSVaultConfigMap added in v0.5.0

func WithSOPSVaultConfigMap() Option

WithSOPSVaultConfigMap indicates that the legacy kustomize-controller flag `--sops-vault-configmap` is set.

func WithSTSEndpoint added in v0.5.0

func WithSTSEndpoint(provider, endpoint string) Option

WithSTSEndpoint sets the legacy `Bucket.spec.sts.provider` and `Bucket.spec.sts.endpoint` values, when present.

func WithSecretRefAuth added in v0.5.0

func WithSecretRefAuth() Option

WithSecretRefAuth indicates that `.spec.secretRef` provides static authentication credentials.

func WithSecretRefCerts added in v0.5.0

func WithSecretRefCerts() Option

WithSecretRefCerts indicates that certificates or CAs are provided by `.spec.secretRef`.

func WithServiceProvider added in v0.5.0

func WithServiceProvider(provider string) Option

WithServiceProvider sets the Flux object's service provider, e.g. `aws`.

type SPIFFEPeerAuthorization

type SPIFFEPeerAuthorization struct {
	// ID is set when the annotation is an exact SPIFFE ID.
	ID *spiffeid.ID
	// Prefix is set when the annotation is a SPIFFE ID prefix.
	Prefix *spiffeid.ID
	// TrustDomain is set when the annotation is a SPIFFE Trust Domain.
	TrustDomain *spiffeid.TrustDomain
	// UseSelfTrustDomain is set when the parsed value contains the special
	// `self` symbol. When set alone, it refers to the entire trust domain
	// of our own X509-SVID. When set together with ID or Prefix, the ID or
	// prefix carries the path and its trust domain must be replaced by the
	// trust domain of our own X509-SVID.
	UseSelfTrustDomain bool
}

SPIFFEPeerAuthorization is a SPIFFE ID parsed either from a `*.fluxcd.io` ServiceAccount annotation, or from a controller flag. At most one of ID, Prefix or TrustDomain is set. UseSelfTrustDomain may be set alone, or together with ID or Prefix to indicate that their trust domain must be replaced by the trust domain of our own X509-SVID.

func ParseSPIFFEID

func ParseSPIFFEID(value string) (*SPIFFEPeerAuthorization, error)

ParseSPIFFEID parses a SPIFFE ID with the following rules:

  • `spiffe://<trust domain>` as a SPIFFE Trust Domain.
  • `spiffe://<trust domain>/<path>` as an exact SPIFFE ID.
  • `spiffe://<trust domain>/<prefix>/` as a SPIFFE ID prefix. The trailing slash identifies a prefix.
  • `spiffe://self` as a symbol for the SPIFFE Trust Domain of our own X509-SVID.
  • `spiffe://self/<path>` as an exact SPIFFE ID in the trust domain of our own X509-SVID.
  • `spiffe://self/<prefix>/` as a SPIFFE ID prefix in the trust domain of our own X509-SVID.

At most one of ID, Prefix or TrustDomain is set. UseSelfTrustDomain is set alone for `spiffe://self`, and together with ID or Prefix for the `spiffe://self` path forms. At least one field of the SPIFFEPeerAuthorization will always be set i.e. this function never returns a zero-value SPIFFEPeerAuthorization.

type Spec added in v0.5.0

type Spec struct {
	// Auth is the validated authentication specification. It is nil when there
	// is no authentication configuration.
	Auth *AuthSpec

	// MTLS is the validated mTLS specification. It is nil when the
	// ServiceAccount did not opt into mTLS.
	MTLS *MTLSSpec
}

Spec is the fully validated specification extracted from the Flux object context and, when object-level workload identity is configured, the ServiceAccount's annotations. It is the shared build result: the auth package consumes Auth and the mTLS package consumes MTLS.

func BuildSpec added in v0.5.0

func BuildSpec(opts ...Option) (*Spec, error)

BuildSpec applies all the API validation rules to the given inputs and returns the fully parsed and validated specification. It must be called even when no ServiceAccount is configured, as some inputs (e.g. the kubeconfig ConfigMap cluster resource) are validated and parsed regardless.

type TransitEngineSpec added in v0.5.0

type TransitEngineSpec struct {
	// LoginPath is the HTTP path in the transit engine where the request for
	// login must be sent.
	LoginPath string
	// Role is the role to use when authenticating against the transit engine.
	Role string
}

TransitEngineSpec is the validated transit engine specification.

Jump to

Keyboard shortcuts

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