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
- func GetAWSRegionFromArtifactRegistryInput(registryInput string) string
- func GetAWSRegionFromCodeCommitURL(gitURL string) (string, error)
- func GetAWSRoleSessionName(sa, ns, region string) string
- func GetDefaultAudienceGCP(workloadIdentityProvider string) string
- func GetRegistryFromArtifactRepository(artifactRepository string) (string, error)
- func ParseArtifactRepository(serviceProvider, artifactRepository string) (string, error)
- func ParseClusterAddress(address string) (string, error)
- func ParseGitRepository(serviceProvider, gitURL string) (string, error)
- type AWSClusterSpec
- type AWSSpec
- type AuthSpec
- type AzureClusterSpec
- type AzureSpec
- type CredentialSpec
- type DockerHubSpec
- type GCPSpec
- type MTLSSPIFFESpec
- type MTLSSpec
- type Option
- func WithAnnotations(annotations map[string]string) Option
- func WithCertSecretRef() Option
- func WithGitHubEnterpriseServer() Option
- func WithImagePullSecrets() Option
- func WithKubeConfigAudiences(audiences string) Option
- func WithKubeConfigCluster(cluster string) Option
- func WithOCI() Option
- func WithSOPSVaultConfigMap() Option
- func WithSTSEndpoint(provider, endpoint string) Option
- func WithSecretRefAuth() Option
- func WithSecretRefCerts() Option
- func WithServiceProvider(provider string) Option
- type SPIFFEPeerAuthorization
- type Spec
- type TransitEngineSpec
Constants ¶
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
const ( // AnnotationDockerHubOIDCConnectionID specifies the Docker Hub OIDC // connection ID for the ServiceAccount. AnnotationDockerHubOIDCConnectionID = GroupAuthDockerHub + "/oidc-connection-id" )
Docker Hub annotation keys.
const (
// GroupCore is the core API group for Flux.
GroupCore = "fluxcd.io"
)
Top-level group.
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
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.
func GetAWSRegionFromCodeCommitURL ¶ added in v0.5.0
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
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
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
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
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
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
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.
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
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
WithKubeConfigAudiences sets the value of the legacy `audiences` key of the kubeconfig ConfigMap, when present.
func WithKubeConfigCluster ¶ added in v0.5.0
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
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
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
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.