Getting started with Yandex Lockbox
Create your first secret and get its content.
A secret is a set of versions that store your data. A version contains sets of keys and values:
- A key is a non-secret name that identifies a value.
- The value is your secret data.
Versions can't be changed. Whenever you need to change the number of key-value pairs or their content, you must create a new version.
Creating secrets
To create a secret:
-
In the management console, select the folder to create a secret in.
-
In the list of services, select Yandex Lockbox.
-
Click Create secret.
-
In the Name field, enter a name for the secret.
-
(optional) In the KMS key field, specify an existing key or create a new one.
The specified KMS key is used to encrypt your secret. If you omit the key, the secret is encrypted with a special system key.
Tip
By using your own KMS key you can take full advantage of Yandex Key Management Service.
-
Under Version:
- In the Key field, enter a non-secret ID.
- In the Value field, enter the confidential data you want to store.
- Click Add pair.
- (optional) Repeat the steps to add more data.
-
Click Create.
If you don't have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
View a description of the CLI create secret command:
yc lockbox secret create --help
-
Run the command, specifying the secret name and the secret description in the parameters:
yc lockbox secret create --name <secret name> --description <secret description> --payload '[{"key": "<key>", "text_value": "<text value>"}[,{"key": "<key>", "text_value": "<text value>"}]]' --cloud-id <cloud ID> --folder-name <folder name>
Result:
id: e6q2ad0j9b55tk3d781j folder_id: b1gktjk2rg494evcsd2a created_at: "2021-11-08T19:23:00.383Z" name: <secret name> description: <secret description> status: ACTIVE current_version: id: g6q4fn3b6okjkckanaib secret_id: e6e2ei4u9b55gh2d561j created_at: "2021-11-08T19:23:00.383Z" status: ACTIVE payload_entry_keys: - <key>
Get the content of the secret
Roles required to get a secret
If you specified your KMS key when creating a secret, assign for it the role kms.keys.encrypterDecrypter: it's needed to encrypt and decrypt the secret.
Get the content of the secret
To get the content of the secret, access it using the API. If you make a request without specifying a version, the content of the current (latest) version is returned.
You can use this logic in scripts, services, and applications where you need to use the content of your secret.
To get the content of the secret:
-
Get an IAM token required for authentication and save it to the variable:
export IAM_TOKEN=`yc iam create-token`
You can also get an IAM token for your service account from inside the VM that the token is linked to. To do this, send a request to the metadata service. An example with the jq utility:
export IAM_TOKEN=`curl -H Metadata-Flavor:Google http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | jq -r .access_token`
-
Run the request:
curl -X GET -H "Authorization: Bearer ${IAM_TOKEN}" \ https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/<ID of the secret>/payload