Documentation
¶
Overview ¶
Package clustercfg is used to parse an byte array and returns a ZarfCluster
Index ¶
- Constants
- Variables
- func CanonicalYAMLPath(yamlPath string) (string, error)
- func DecryptAtPath(src []byte, yamlPath, password string) ([]byte, error)
- func DecryptConfig(src []byte, password string) ([]byte, []string, error)
- func DecryptRegistryAuth(dis *cluster.ZarfCluster, password string) error
- func DecryptValue(value, password string) (string, error)
- func EncryptAtPath(src []byte, yamlPath, password string, reencrypt bool) ([]byte, error)
- func EncryptConfig(src []byte, password string, reencrypt bool) ([]byte, []string, error)
- func EncryptValue(value, password string) (string, error)
- func Parse(_ context.Context, b []byte) (cluster.ZarfCluster, error)
- func PathIsDecryptable(yamlPath string) bool
- func RekeyAtPath(src []byte, yamlPath, oldPassword, newPassword string) ([]byte, error)
- func RekeyConfig(src []byte, oldPassword, newPassword string) ([]byte, []string, error)
- func ResolveVaultPassword(passwordFile string) (string, error)
- func VerifyRegistryAuth(dis *cluster.ZarfCluster, password string) error
Constants ¶
const AnsibleVaultPasswordEnvVar = "ANSIBLE_VAULT_PASSWORD"
AnsibleVaultPasswordEnvVar is a secondary environment variable checked for the Ansible Vault password, used by ansible-vault itself. VaultPasswordEnvVar takes precedence when both are set.
const VaultPasswordEnvVar = "CARGOSHIP_VAULT_PASSWORD"
VaultPasswordEnvVar is the environment variable checked for the Ansible Vault password when no --vault-password-file flag is given.
Variables ¶
var ErrAlreadyEncrypted = errors.New("value is already Ansible Vault-encrypted")
ErrAlreadyEncrypted reports that the value at the requested path is Ansible Vault ciphertext already, so encrypting it again would bury the plaintext under a second layer that nothing unwraps.
var ErrNotEncrypted = errors.New("value is not Ansible Vault-encrypted")
ErrNotEncrypted reports that the value at the requested path is plaintext, so there is nothing to decrypt. Rewriting it anyway would be a no-op that still rewrote the file, which is worth saying out loud rather than reporting as success.
var ErrWrappedTwice = errors.New("value is Ansible Vault-encrypted more than once")
ErrWrappedTwice reports that the value at the requested path is ciphertext whose plaintext is itself ciphertext -- what encrypt-path --force produces. Rekeying it would move the outer layer onto the new password and leave the inner one on the old, which no single password can read back, so it is refused rather than half done.
Functions ¶
func CanonicalYAMLPath ¶ added in v0.21.0
CanonicalYAMLPath returns yamlPath as go-yaml spells it, so that the several ways of writing one path -- "$.spec.x", ".spec.x" and "spec.x" -- come back as the same string. A caller given a list of paths needs that to tell whether two of them name the same value, which is worth catching before the first one has been rewritten.
func DecryptAtPath ¶ added in v0.21.0
DecryptAtPath returns src with the Ansible Vault ciphertext at yamlPath replaced by its plaintext, preserving every other byte of src for the same reasons, and by the same means, as EncryptAtPath.
The plaintext is written in whichever scalar style holds it faithfully: plain where YAML allows it, a literal block for something multi-line such as a PEM certificate, and a quoted string for anything the other two would change on the way back in. If the value is plaintext already, it returns ErrNotEncrypted.
func DecryptConfig ¶ added in v0.21.0
DecryptConfig is the inverse of EncryptConfig: it decrypts every vaulted registry credential in src and returns the rewritten document along with the paths it changed. A field that is not ciphertext is skipped, so what comes back is a document with no vaulted credentials left in it however many of them there were to begin with.
func DecryptRegistryAuth ¶ added in v0.15.0
func DecryptRegistryAuth(dis *cluster.ZarfCluster, password string) error
DecryptRegistryAuth decrypts any Ansible Vault-encrypted Username, Password, or Token fields on dis.Spec.Config.Registries in place, along with an inline TLS CA certificate given the same way. Fields that don't carry the $ANSIBLE_VAULT header are left untouched.
A CA certificate is public and does not need encrypting, but accepting one encrypted means a document can be vaulted as a whole without cargoship rejecting the parts that did not have to be. The decrypted TLS settings are validated here, since load time saw only ciphertext.
func DecryptValue ¶ added in v0.21.0
DecryptValue decrypts a single Ansible Vault-encrypted value with the given password, returning the plaintext EncryptValue was given.
DecryptRegistryAuth is what an apply runs; this is for the operator reading a value back out of a configuration by hand.
func EncryptAtPath ¶ added in v0.21.0
EncryptAtPath returns src with the scalar at yamlPath replaced by its Ansible Vault ciphertext, written as a literal block scalar. Every other byte of src is preserved -- comments, key order, quoting and indentation elsewhere in the document all survive, so the result is still the operator's file rather than a re-rendering of it.
That byte-level splice is deliberate. Replacing the node in the parsed document and printing it back would be shorter, but go-yaml re-indents a multi-line literal by slicing each continuation line, which silently truncates ciphertext nested inside a sequence -- which is where every registry credential lives.
If the value is ciphertext already, it returns ErrAlreadyEncrypted unless reencrypt is set.
func EncryptConfig ¶ added in v0.21.0
EncryptConfig encrypts every registry credential in src that cargoship decrypts at apply time -- each registry's auth.user, auth.pass, auth.token and tls.ca -- and returns the rewritten document along with the paths it changed. Everything else is left exactly as it was, by the same byte-level splice EncryptAtPath uses.
A field that is absent, empty, or encrypted already is skipped rather than treated as an error, so running this over a configuration that is partly vaulted finishes the job, and running it twice changes nothing the second time. Pass reencrypt to wrap values that are ciphertext already.
A value that is encrypted already has to be one this password can read, and it is an error when it is not. Skipping it quietly would leave the file holding ciphertext under two different vault passwords, and an apply decrypts a registry's fields with one password, so the result would be a configuration no password can read back -- found out about at apply time, several phases in, rather than here.
func EncryptValue ¶ added in v0.15.0
EncryptValue encrypts value with the given Ansible Vault password, producing a string suitable for use as a registry auth field (see DecryptRegistryAuth).
func PathIsDecryptable ¶ added in v0.21.0
PathIsDecryptable reports whether yamlPath names a field cargoship decrypts at apply time. A value encrypted anywhere else reaches the host as ciphertext, because nothing unwraps it.
func RekeyAtPath ¶ added in v0.21.0
RekeyAtPath returns src with the Ansible Vault ciphertext at yamlPath re-wrapped under newPassword, preserving every other byte of src by the same splice EncryptAtPath uses.
The plaintext is never rendered back into the document. The value is decrypted, encrypted again, and spliced in as ciphertext, so the plaintext exists only as a string in memory -- which is the whole point of rekeying as one operation rather than a decrypt-file followed by an encrypt-file, where the file holds the plaintext in between. It also means a value renderScalar would refuse to write back, one that is not valid UTF-8, rekeys without trouble, because nothing here has to express it as YAML.
A value that is plaintext returns ErrNotEncrypted, and one wrapped more than once ErrWrappedTwice.
func RekeyConfig ¶ added in v0.21.0
RekeyConfig re-wraps every vaulted registry credential in src under newPassword and returns the rewritten document along with the paths it changed. A field that is absent, empty, or plaintext is skipped, so what comes back is a document whose ciphertext is all under one password and whose plaintext was never written anywhere.
Every value it touches has to be readable with oldPassword, and it is an error when one is not. There is no way to rekey a file already holding ciphertext under two passwords into a working state -- an apply reads a registry's fields with a single password -- so stopping is the only answer that does not produce a configuration no password can read back.
Unlike EncryptConfig this is not idempotent, and cannot be: Ansible Vault salts every encryption, so a second run rewrites the same values to different ciphertext. Passing the same password as both old and new is that property put to use rather than a mistake: every value comes back under a fresh salt, readable with the password the file already carried.
func ResolveVaultPassword ¶ added in v0.15.0
ResolveVaultPassword returns the Ansible Vault password to use for decrypting registry credentials. If passwordFile is set, its contents are read and used. Otherwise it falls back to the CARGOSHIP_VAULT_PASSWORD environment variable, then to ANSIBLE_VAULT_PASSWORD. An empty return value with a nil error means no password was configured.
func VerifyRegistryAuth ¶ added in v0.20.1
func VerifyRegistryAuth(dis *cluster.ZarfCluster, password string) error
VerifyRegistryAuth reports whether every Ansible Vault-encrypted registry value in dis can be decrypted with password, and whether what comes out is usable, leaving dis unchanged.
The values are only needed once the engine configuration is written, which is several phases into an apply -- long after cargoship has connected to every host, and on a sync, after it has started draining nodes. A password that was never supplied, or one that does not match the document, is worth finding out about before any of that happens rather than partway through it, so a command calls this as soon as it has resolved the password.
Types ¶
This section is empty.
Source Files