Resources / Secret

Secret

A held secret, such as a cloud credential, a TLS private key, a signing key or a deploy token. The value is write-only (it can be created and replaced, and no get, list or watch returns it), is sealed in the store under a per-project key, and is delivered only by the audited reveal path or into a sandbox that references the secret. Status shows metadata about the value (version, fingerprint, expiry, consumers), never the value.

Overview

APIsecrets.etorm.com/v1alpha1
Resourcesecrets (cluster-scoped inside its cluster)
Short namesnone
Available inthe platform and project clusters
Statuswritten by a controller through /status

Minimal example

apiVersion: secrets.etorm.com/v1alpha1
kind: Secret
metadata:
  name: example
spec:
  type: opaque

Spec

FieldTypeRequiredDefaultAllowedDescription
typestring (one of)yesopaque, password, token, tls, ssh-key, cloud-credential, webhookWhat kind of secret this is; it fixes the key names of the data (password: password and optionally username; token: token; tls: tls.crt and tls.key; ssh-key: private-key and optionally public-key; cloud-credential: credential; webhook: secret and optionally url; opaque: any). Cannot be changed.
descriptionstringup to 200 charactersWhat the secret is for, shown in lists. Never put the value here.
dataobjectWRITE-ONLY. The value as key to base64 string. Accepted on create and update, removed during admission, never returned. At most 32 keys, decoded values together at most 64 KiB.
stringDataobjectWRITE-ONLY. Like data, with plain UTF-8 strings instead of base64. Merged into data.
generateobjectThe platform makes the value instead of you typing it. Cannot be combined with data on create. A generated secret is rotated, never written.
generate.kindstring (one of)yespassword, token, bytes, ed25519password: letters and digits. token: random bytes in base64url. bytes: raw random bytes. ed25519: a signing key pair (private-key seed and public-key). Cannot be changed.
generate.lengthinteger16 to 1024Characters (password), bytes (token, bytes). Default 32; password and token at most 128. Ignored for ed25519.
generate.revealstring (one of)"never"never, onceonce: the value is returned once, in the response of the write that made it (spec.generated), and nowhere else. never: only the reveal path and sandboxes ever receive it.
rotationobjectWhen and how the value changes.
rotation.intervalSecondsintegerat least 3600Rotate generated or issued secrets this often. For a typed secret, the age after which RotationDue is reported (the owner of the value rotates it).
rotation.gracePeriodSecondsinteger36000 to 604800How long the previous version stays deliverable after a new one becomes current.
rotation.requestedAtstringup to 64 charactersChange this string to rotate a generated secret now. Any value is accepted; only a change counts.
expiresAtstringup to 40 charactersWhen the value stops being valid at its owner (RFC 3339). Drives the Expiring and Expired phases.
warnBeforeSecondsintegerat least 0How long before expiresAt the secret is reported as Expiring. Default 7 days; none for an issued secret, which its issuer renews before it ends.
issuerobjectThe value is minted short-lived by a named credential issuer (spec 0039 section 10) and renewed before it ends.
issuer.namestringyesup to 63 charactersName of the issuer component.
issuer.configobject (free-form)Non-secret settings for the issuer (audience, role, scope). At most 4 KiB.
deliveryobjectPublish the value to operators' credential stores. Only in the root cluster and in system projects.
delivery.credentialStoreobjectPut one key of the value into the host credential store under this secret's name, for kinds that name credentials there (a cloud account's credentialRef).
delivery.credentialStore.keystringyesup to 63 charactersWhich key of the data to publish.
bootstrapobjectWhen the platform cannot renew this secret by itself (it expires, or its renewal fails), it asks a person with a BootstrapRequest built from this. Only in the root cluster and in system projects.
bootstrap.purposestringyeslength 1 to 200What the credential is for.
bootstrap.providerstringyeslength 1 to 63Whose credential it is.
bootstrap.stepslist of stringyesup to 20 itemsThe exact steps for the person. Never a value.
custodyobjectThis secret stands for a platform key that exists outside the platform (a master key) and holds no value: it is Ready while custodians have confirmed recently (Approval of type Custody). Type must be opaque; it cannot be revealed.
custody.holderslist of stringyesup to 10 itemsWho can produce the key (names of people or roles, not contact details).
custody.verifyEverySecondsintegeryesat least 3600How often custodians must confirm.
sealedobject (free-form)Server-managed ciphertext of the sealed versions. Never settable by a client and never returned.

Status

FieldTypeRequiredDefaultAllowedDescription
phasestring (one of)Pending, Ready, Expiring, Expired, FailedPending: no value yet. Ready. Expiring: inside warnBeforeSeconds of expiresAt. Expired. Failed: an issuer could not renew it.
conditionslist of objectDetailed state: Sealed, Fresh, RotationDue, Expiring, Delivered.
conditions[].typestringAspect.
conditions[].statusstringTrue or False.
conditions[].reasonstringMachine-readable reason.
conditions[].messagestringHuman-readable detail
typestringThe secret's type.
keyslist of stringNames of the keys in the current value.
versionintegerThe current version
previousVersionintegerThe previous version
previousValidUntilstringWhen the previous version stops being deliverable (RFC 3339).
createdAtstringWhen the first version was made (RFC 3339).
rotatedAtstringWhen the current version was made (RFC 3339).
expiresAtstringCopy of spec.expiresAt.
nextRotationAtstringWhen the lifecycle operator will rotate it
fingerprintstringTwelve hex digits identifying the current value under the project key. Not a hash of the value: it cannot be used to guess it.
dataKeyIdintegerId of the project data key the current version is sealed under.
keyVersionintegerVersion of the platform key that wraps the project data key.
consumerslist of objectObjects that reference this secret and principals bound to it.
consumers[].groupstringAPI group of the consumer.
consumers[].kindstringKind of the consumer
consumers[].namestringName of the consumer.

Columns in listings

ColumnFrom
Type.spec.type
Version.status.version
Phase.status.phase
Expires.status.expiresAt
Fingerprint.status.fingerprint

All resources