[Yandex Cloud documentation](../../../index.md) > [Yandex Cloud Functions](../../index.md) > [Step-by-step guides](../index.md) > Managing a function > Providing Yandex Lockbox secrets

# Providing Yandex Lockbox secrets to a function

{% note info %}

This feature is in the [Preview](../../../overview/concepts/launch-stages.md) stage.

{% endnote %}

[Yandex Lockbox](../../../lockbox/index.md) is designed to store secrets. You can provide a Yandex Lockbox secret to a function via an [environment variable](../../concepts/runtime/environment-variables.md#env).

For a [function](../../concepts/function.md) to get access to a [secret](../../../lockbox/concepts/secret.md), edit its parameters to specify a [service account](../../../iam/concepts/users/service-accounts.md) with the following [roles](../../../iam/concepts/access-control/roles.md) assigned:
* `lockbox.payloadViewer` for the secret ([how to assign access permissions for a secret](../../../lockbox/operations/secret-access.md)).
* `kms.keys.encrypterDecrypter` for the encryption [key](../../../kms/concepts/key.md) if the secret was created using a [Yandex Key Management Service](../../../kms/index.md) key ([how to assign access permissions for an encryption key](../../../kms/operations/key-access.md)).

A [Yandex Lockbox](../../../lockbox/index.md) secret provided to a function is cached in [Yandex Cloud Functions](../../index.md). After the service account loses access to the secret, the function may retain it for up to five minutes.

Providing secrets creates a new function version. You cannot provide secrets to an existing version.

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), navigate to the [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) containing the function.
  1. Navigate to **Cloud Functions**.
  1. Select the function to provide a Yandex Lockbox secret to.
  1. Navigate to the **Editor** tab.
  1. Under **Parameters**, specify:
     * In the **Service account** field, the service account with the `lockbox.payloadViewer` role.
     * In the **Lockbox secrets** field:
       * Name of the environment variable that will store the secret.
       * Secret ID.
       * Secret version ID.
       * Key of a key-value pair in the secret version.
  1. Click **Add**.

     You can provide multiple secrets to a function. To do this, click **Add**.
  1. Click **Save changes**. This will create a new version of the function with the specified secrets.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To provide a Yandex Lockbox secret to a function, run this command:

  {% note warning %}

  If secrets were already provided to the previous function version, they will be overwritten.

  {% endnote %}

  ```bash
  yc serverless function version create \
    --function-name=test \
    --runtime nodejs16 \
    --entrypoint index.main \
    --memory 128m \
    --execution-timeout 5s \
    --source-version-id vfdsdeqa1s2d3******** \
    --service-account-id bfbtfcp0o9i8******** \
    --secret environment-variable=KEY,id=fc3q4aq3w5e6********,version-id=fc3gvvz4x5c6********,key=secret-key
  ```

  Where:
  * `--function-name`: Function name.
  * `--runtime`: Runtime.
  * `--entrypoint`: Entry point in `<function_file_name>`.`<handler_name>` format.
  * `--memory`: Amount of RAM.
  * `--execution-timeout`: Maximum function execution time before timeout.
  * `--source-version-id`: ID of the function version from which you want to copy the code.
  * `--service-account-id`: ID of the service account with the `lockbox.payloadViewer` role.
  * `--secret`:
    * `environment-variable`: Name of the environment variable that will store the secret.
    * `id`: Secret ID.
    * `version-id`: Secret version ID.
    * `key`: Key of a key-value pairs in the secret version.

    You can provide multiple secrets to a function. To do this, specify `--secret` as many times as needed.

- Terraform {#tf}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. Open the Terraform configuration file and add the `secrets` section to the function description:

     ```hcl
     resource "yandex_function" "test-function" {
       name               = "test-function"
       description        = "Test function"
       user_hash          = "first-function"
       runtime            = "python37"
       entrypoint         = "main"
       memory             = "128"
       execution_timeout  = "10"
       service_account_id = "<service_account_ID>"
       tags               = ["my_tag"]
       secrets {
         id                   = "<secret_ID>"
         version_id           = "<secret_version_ID>"
         key                  = "<secret_1_key>"
         environment_variable = "<environment_variable_1_name>"
       }
       secrets {
         id                   = "<secret_ID>"
         version_id           = "<secret_version_ID>"
         key                  = "<secret_2_key>"
         environment_variable = "<environment_variable_2_name>"
       }

        content {
          zip_filename = "<path_to_ZIP_archive>"
        }
     }
     ```

     Where:
     * `secrets`: Section with secret configuration. It contains the following settings:
       * `id`: Secret ID. This is a required setting.
       * `version_id`: Secret version ID. This is a required setting.
       * `key`: Key of a secret version’s key-value pair that will be stored in the environment variable. This is a required setting.
       * `environment_variable`: Name of the environment variable that will store the secret. This is a required setting.
  
     For more on the properties of the `yandex_function` resource, see [this provider guide](../../../terraform/resources/function.md).

  1. Apply the changes:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

  You can check the function update and its settings in the [management console](https://console.yandex.cloud).

- API {#api}

  To provide a Yandex Lockbox secret to a function, use the [createVersion](../../functions/api-ref/Function/createVersion.md) REST API method for the [Function](../../functions/api-ref/Function/index.md) resource or the [FunctionsService/CreateVersion](../../functions/api-ref/grpc/Function/createVersion.md) gRPC API call.

{% endlist %}