How to use environment values of type SECRET "On following submissions"?

Posted October 18, 2020 1.5k views
DockerDigitalOcean App Platform

Your App Specification Reference says the following for the envs/value:

String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

Could you please clarify what the last sentence means.

For example, I am declaring an environment variable in my yaml file as follows:

  "scope": "RUN_AND_BUILD_TIME",
  "type": "SECRET",

Now, based on this:

On following submissions, the encrypted value should be used.

It is not clear if I must re-fetch the yaml file from DigitalOcean in order to get the encrypted values for the value keys? So that on the following submission, my yaml file will have this:

  "scope": "RUN_AND_BUILD_TIME",
  "type": "SECRET",
  "value": ";lkajsdf;1lkm23r920s,lc;naksdjv;aldkjvad"

Is this correct, or am I misinterpreting the documentation?

Finally, if this is the case, how do I update the value of the value with the new api key when we need to? Do we go to the UI and update it there, and then refetch the yaml file again?

It is a bit confusing, please could you explain the workflow of setting AND updating the values of environment variables of type SECRET


These answers are provided by our Community. If you find them useful, show some love by clicking the heart. If you run into issues leave a comment, or add your own answer to help others.

Submit an Answer
1 answer

@ReWild 👋

Your assumptions on this are correct. When you’re submitting a new app or changing values of secret envs, you should submit the spec (or update via the UI) with those values unencrypted. The spec you get in response to that, and the one now persisted as your app desired state, will have that secret value encrypted in-place to look something like this:

  "scope": "RUN_AND_BUILD_TIME",
  "type": "SECRET",
  "value": "EV[1:xWTjge/c/Oe6kPy0/AFs916m3LcXMzWO:/RoXzy12ATYCexS2h50jI2tJFTQ9+E415Yldtl4l5Ua0UeHrERbI6epjcnehWKZZ]"

As you make updates to your app spec, if you don’t intend to change those encrypted values, then you should just submit with the in-place encrypted values unchanged. If you’d like to make a change to the value itself, you just need to resubmit the spec with the plain-text value, and it will again be encrypted in-place on the app spec.

  • Thanks, now it makes perfect sense. So DigitalOcean will detect if I am changing the value or submitting the encrypted value. Great.

    Does it also mean it is safe to git-commit the spec file with the encrypted values? Or would you still advise against it?

    I’m thinking about how we should git-track the spec file, but not the sensitive data.

    More to that, what happens if a SECRETE value gets changed in the UI, and then a yaml file is re-submitted from the command line, and the yaml file has an encrypted value. Will the yaml-file version override the one entered in the UI?

    • Yep, it is safe to git-commit these with your spec. This was one of the drivers behind the feature — inspired by the ejson model.

      • A few more questions.
        Is there any encryption key rotation?
        What is the key bound to (digitalocean account unique id, project id, app id, …)? I.e. what if we use the spec file with the encrypted values to create a new app from it, will it understand the value, or will it treat the encrypted values as NEW RAW value, and encrypt those already-encrypted values?

        • These are really good questions — glad you’re asking.

          We currently don’t expose a key rotation mechanism to users, but will be introducing this in the future. You actually don’t even have access to the encryption key directly today as a user.

          The encryption key is specific to each app — a different key is used for every app.

          If you try to create a new app with a secret env value that is already encrypted in-place from another app, you’ll receive a validation error on the response. Similarly, if you try to update an existing app with an encrypted value from a different app, you’ll get a validation error.

      • Just to clarify - because the first two times I read this I misunderstood - it’s okay to commit the encrypted version to git (after doctl has changed the value), but you would not want to commit the unencrypted version to commit. Which, if I’m understanding correctly, means that secrets in app.yaml only work if deploying via doctl, and not via the UI.