⚠️ Work in Progress
You are viewing development documentation built from the latest commit on main. APIs and features are subject to change.

External Secrets Builders

External Secrets Builders - External Secrets Resource Constructors

Go Reference Go Reference

The externalsecrets package provides the generated constructors and the admissible sugar for External Secrets Operator Kubernetes resources. These are the low-level building blocks used by Kure’s higher-level stack and workflow packages.

Overview

Every kind is built the same way: the generated Create<Kind> wrapper gives you an object carrying identity only, and the upstream external-secrets struct is the construction API — set Spec fields directly, or through the few Set*/Add* helpers the builder contract admits.

Each block on this page is the body of an Example function in example_test.go, which go test runs: it imports this package as externalsecrets, github.com/go-kure/kure/pkg/kubernetes, the upstream API as esv1 "github.com/external-secrets/external-secrets/apis/externalsecrets/v1", metav1 "k8s.io/apimachinery/pkg/apis/meta/v1", time, and fmt for the line that prints what the example built.

Constructors

Every kind this package registers has a generated Create<Kind> wrapper in zz_generated_create.go, produced from the scheme by pkg/kubernetes/internal/gen (make gen-builders, checked by make check-builders in CI). A wrapper delegates to kubernetes.Create[T] and emits TypeMeta and identity only: no default, no label, no spec value. Namespaced kinds take (name, namespace), cluster-scoped kinds take (name).

obj := externalsecrets.CreateExternalSecret("my-secret", "default")
cl := externalsecrets.CreateClusterSecretStore("global-vault")
fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name, cl.Kind, cl.Name)

There is no second construction path. The config-struct layer this package used to carry (externalsecrets.ExternalSecret(&externalsecrets.ExternalSecretConfig{...}), SecretStore, ClusterSecretStore) was retired by release 2 of the builder contract: it reached 2 of an ExternalSecret’s 7 spec fields (secretStoreRef and data) and was otherwise a copy of the assignments below. The release 2 migration notes map every removed field to the upstream field that replaces it. No hand-written Create* helper for a spec fragment remains either — a sub-type that is not a client.Object takes a struct literal, which is shorter and shows every field being set.

The kinds this package registers, their scope, and what stated that scope are rows in the generated Supported kinds and field maturity tables. The sections below are worked examples, not the coverage list.

See the Kubernetes Builders page for the full builder contract: construction, sugar admission classes, purity and the migration ledgers.

Supported Resources

External Secrets

es := externalsecrets.CreateExternalSecret("my-secret", "default")
es.Spec.SecretStoreRef = esv1.SecretStoreRef{Name: "vault", Kind: "ClusterSecretStore"}
es.Spec.Target = esv1.ExternalSecretTarget{Name: "my-secret"}
externalsecrets.AddExternalSecretData(es, esv1.ExternalSecretData{
    SecretKey: "password",
    RemoteRef: esv1.ExternalSecretDataRemoteRef{Key: "secret/data/myapp"},
})
externalsecrets.SetRefreshInterval(es, metav1.Duration{Duration: time.Hour})
fmt.Println(es.Spec.Data[0].SecretKey, es.Spec.RefreshInterval.Duration)

Secret Stores

ss := externalsecrets.CreateSecretStore("aws-store", "default")
externalsecrets.SetSecretStoreProvider(ss, &esv1.SecretStoreProvider{
    AWS: &esv1.AWSProvider{Service: esv1.AWSServiceSecretsManager, Region: "us-east-1"},
})
ss.Spec.Controller = "my-controller"
fmt.Println(ss.Spec.Provider.AWS.Region, ss.Spec.Controller)

Cluster Secret Stores

css := externalsecrets.CreateClusterSecretStore("global-vault")
externalsecrets.SetClusterSecretStoreProvider(css, &esv1.SecretStoreProvider{
    AWS: &esv1.AWSProvider{Service: esv1.AWSServiceSecretsManager, Region: "us-east-1"},
})
fmt.Println(css.Spec.Provider.AWS.Region)

Modifier Functions

Update existing resources:

es := externalsecrets.CreateExternalSecret("my-secret", "default")
ss := externalsecrets.CreateSecretStore("aws-store", "default")
css := externalsecrets.CreateClusterSecretStore("global-vault")
provider := &esv1.SecretStoreProvider{
    AWS: &esv1.AWSProvider{Service: esv1.AWSServiceSecretsManager, Region: "us-east-1"},
}

// Replace the full spec
es.Spec = esv1.ExternalSecretSpec{Target: esv1.ExternalSecretTarget{Name: "my-secret"}}

// Granular updates
externalsecrets.AddExternalSecretData(es, esv1.ExternalSecretData{
    SecretKey: "password",
    RemoteRef: esv1.ExternalSecretDataRemoteRef{Key: "secret/data/myapp"},
})
externalsecrets.AddDataFrom(es, esv1.ExternalSecretDataFromRemoteRef{
    Extract: &esv1.ExternalSecretDataRemoteRef{Key: "secret/data/shared"},
})
es.Spec.SecretStoreRef = esv1.SecretStoreRef{Name: "vault", Kind: "ClusterSecretStore"}

externalsecrets.SetSecretStoreProvider(ss, provider)
ss.Spec.Controller = "my-controller"

externalsecrets.SetClusterSecretStoreProvider(css, provider)
css.Spec.Controller = "global"

// Labels and annotations use the generic helpers, which work over any object
// with ObjectMeta -- this package carries no per-kind metadata helpers
kubernetes.AddLabel(es, "app", "myapp")
kubernetes.AddAnnotation(ss, "desc", "value")
kubernetes.AddLabel(css, "team", "platform")

fmt.Println(len(es.Spec.Data), es.Spec.DataFrom[0].Extract.Key, css.Spec.Controller, es.Labels["app"])