You are browsing unreleased documentation. See the latest documentation here.
kong.vault
This module can be used to resolve, parse, and verify vault references.
kong.vault.is_reference(reference)
Checks if the passed in reference looks like a reference. Valid references start with ‘{vault://’ and end with ‘}’.
If you need more thorough validation,
use kong.vault.parse_reference
.
Parameters
-
reference (
string
): reference to check
Returns
-
boolean
:true
is the passed in reference looks like a reference, otherwisefalse
Usage
kong.vault.is_reference("{vault://env/key}") -- true
kong.vault.is_reference("not a reference") -- false
kong.vault.parse_reference(reference)
Parses and decodes the passed in reference and returns a table containing its components.
Given a following resource:
"{vault://env/cert/key?prefix=SSL_#1}"
This function will return following table:
{
name = "env", -- name of the Vault entity or Vault strategy
resource = "cert", -- resource where secret is stored
key = "key", -- key to lookup if the resource is secret object
config = { -- if there are any config options specified
prefix = "SSL_"
},
version = 1 -- if the version is specified
}
Parameters
-
reference (
string
): reference to parse
Returns
-
table|nil
: a table containing each component of the reference, ornil
on error -
string|nil
: error message on failure, otherwisenil
Usage
local ref, err = kong.vault.parse_reference("{vault://env/cert/key?prefix=SSL_#1}") -- table
kong.vault.get(reference)
Resolves the passed in reference and returns the value of it.
Parameters
-
reference (
string
): reference to resolve
Returns
-
string|nil
: resolved value of the reference -
string|nil
: error message on failure, otherwisenil
Usage
local value, err = kong.vault.get("{vault://env/cert/key}")
kong.vault.update(options)
Helper function for secret rotation based on TTLs. Currently experimental.
Parameters
-
options (
table
): options containing secrets and references (this function modifies the input options)
Returns
-
table
: options with updated secret values
Usage
local options = kong.vault.update({
cert = "-----BEGIN CERTIFICATE-----...",
key = "-----BEGIN RSA PRIVATE KEY-----...",
cert_alt = "-----BEGIN CERTIFICATE-----...",
key_alt = "-----BEGIN EC PRIVATE KEY-----...",
["$refs"] = {
cert = "{vault://aws/cert}",
key = "{vault://aws/key}",
cert_alt = "{vault://aws/cert-alt}",
key_alt = "{vault://aws/key-alt}",
}
})
-- or
local options = {
cert = "-----BEGIN CERTIFICATE-----...",
key = "-----BEGIN RSA PRIVATE KEY-----...",
cert_alt = "-----BEGIN CERTIFICATE-----...",
key_alt = "-----BEGIN EC PRIVATE KEY-----...",
["$refs"] = {
cert = "{vault://aws/cert}",
key = "{vault://aws/key}",
cert_alt = "{vault://aws/cert-alt}",
key_alt = "{vault://aws/key-alt}",
}
}
kong.vault.update(options)
kong.vault.try(callback, options)
Helper function for automatic secret rotation. Currently experimental.
Parameters
-
callback (
function
): callback function -
options (
table
): options containing credentials and references
Returns
-
string|nil
: return value of the callback function -
string|nil
: error message on failure, otherwisenil
Usage
local function connect(options)
return database_connect(options)
end
local connection, err = kong.vault.try(connect, {
username = "john",
password = "doe",
["$refs"] = {
username = "{vault://aws/database-username}",
password = "{vault://aws/database-password}",
}
})