From 1f2c25f7e71154c6cb30a6474a409a232f72f7d6 Mon Sep 17 00:00:00 2001 From: linda Date: Mon, 23 Dec 2024 14:07:30 -0800 Subject: [PATCH 1/6] clear config explanation --- docs/concepts/configuration.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 6efdd64bf..0b5076e2d 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -19,6 +19,9 @@ defang config set API_KEY You can use sensitive config by specifying them in the `environment` section of a service in a `compose.yaml` file without any value, or by specifying an environment key with a `null` value in your Pulumi code. +Either one of list notation or map notation is acceptable for defining your environment variable(s). See below for an example of each. + +#### With List Notation ```yaml services: service1: @@ -27,9 +30,7 @@ services: - API_KEY ``` -You can also use this syntax: - - +#### With Map Notation ```yaml services: service1: From dad7e65a6c227f25fe3a0d6b6efcaf5c2662b5c9 Mon Sep 17 00:00:00 2001 From: linda Date: Mon, 23 Dec 2024 14:08:10 -0800 Subject: [PATCH 2/6] started outlining possible compose page outline --- docs/concepts/compose-support.md | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/concepts/compose-support.md diff --git a/docs/concepts/compose-support.md b/docs/concepts/compose-support.md new file mode 100644 index 000000000..2dd475c33 --- /dev/null +++ b/docs/concepts/compose-support.md @@ -0,0 +1,37 @@ +--- +title: Compose Support +description: Defang supports many of the properties of the Compose specification. +sidebar_position: 160 +--- + +# Compose Support + +This page outlines what properties of the [Compose specification](https://docs.docker.com/compose/compose-file/) Defang supports when writing a `compose.yaml` file. +For a more general overview of how Defang works with Compose, please see our [Compose](/docs/concepts/compose) page. + +### Supported Compose Properties +|Property | Details +|-|- +|`image` | + +### Optional Compose Properties +|Property | Details +|-|- +|`ports` | If left unspecified, a random port will be chosen. +|`memory` | If left unspecified, will resort to default. +|`environment` | + +### Depreciated Compose Properties +|Property | Details +|-|- +|`version` | This top-level element is no longer needed in the Compose file. Instead, Defang uses the most recent schema supported for parsing the file. + +### Unsupported Compose Properties +|Property | Details +|-|- +|`volume` | Volume mounts are not currently supported by Defang, but will not break the file if included. + + + +### Configuration +You can define sensitive environment variables/configuration for Defang by writing out the variable name and leaving it in as a blank or `null` value in the Compose file. See our [Configuration](/docs/concepts/configuration) page for more. \ No newline at end of file From 45053271eece26f267b1a31c1100d5277979071a Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 24 Dec 2024 12:08:09 -0800 Subject: [PATCH 3/6] add config tutorial --- .../configure-environment-variables.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/tutorials/configure-environment-variables.md diff --git a/docs/tutorials/configure-environment-variables.md b/docs/tutorials/configure-environment-variables.md new file mode 100644 index 000000000..2511a98e0 --- /dev/null +++ b/docs/tutorials/configure-environment-variables.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 400 +title: Configure Environment Variables +description: How to configure sensitive environment variables in Defang. +--- + +# Configure Environment Variables + + +This tutorial will show you how to configure sensitive environment variables in Defang. + +## Pre-requisites +* [A `compose.yaml` file in your project](https://docs.docker.com/compose/gettingstarted/) +* [A Defang Account](/docs/concepts/authentication) +* [The Defang CLI](/docs/getting-started#install-the-defang-cli) + +## Step 1 - Go to your `compose.yaml` file +:::info +If you are using [Pulumi](/docs/concepts/pulumi) instead of Compose files to define your application, please see [Using Config With Pulumi](/docs/concepts/configuration#using-config-with-pulumi). +::: + +In your Compose file, you can define a sensitive config variable for your service by leaving it as a **blank or `null` value**. Defang will recognize it as a sensitive value. + +In the example below, let's define `API_KEY` as an environment variable. + +```yaml +services: + service1: + image: image1:latest + environment: + - API_KEY +``` + +The type of notation shown above is called *list notation*. Alternatively, you can use *map notation*, which is also acceptable: +```yaml +services: + service1: + image: image1:latest + environment: + API_KEY: +``` + +## Step 2 - Set the actual value in the Defang CLI +To store the actual (sensitive) value of the variable, open up a terminal and type the command: +```bash +defang config set API_KEY=actualvalue +``` +Remember to replace `API_KEY` with your variable name and `actualvalue` with your actual value. + +:::tip +You can view all of your config variables by doing `defang config ls`. +::: + +### Editing a config value +To edit a value, you can run the command again with an updated value to overwrite the current value: +```bash +defang config set API_KEY=newvalue +``` + +### Removing a config value +To remove a value, run the command: +```bash +defang config rm API_KEY +``` +:::tip +Remember to update your Compose file if you remove an environment variable. +::: + +## Step 3 - Deploy +```bash +defang compose up +``` + +--- +For a deeper discussion on how configuration works in Defang, see our [Configuration docs](/docs/concepts/configuration). From 54df27cb83426c6159c6507beffaeb0e0f7750df Mon Sep 17 00:00:00 2001 From: commit111 Date: Tue, 24 Dec 2024 12:10:29 -0800 Subject: [PATCH 4/6] update compose/config page to not use "secrets" --- docs/concepts/compose.md | 14 +++++--------- docs/concepts/configuration.md | 9 +++++---- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md index 3ae03f43e..12af1d443 100644 --- a/docs/concepts/compose.md +++ b/docs/concepts/compose.md @@ -20,10 +20,10 @@ One thing to keep in mind is that, at the time of this writing, Defang identifie ## Configuration -If you have a service that depends on a secret like an api key, you can set that [secret](./configuration.md) using the CLI: +If you have a service that depends on a [config value](./configuration.md) (such as an API key), you can set it using the CLI: ``` -defang config set --name MY_API_KEY +defang config set MY_API_KEY ``` and then connect it to the service by specifying it in the `compose.yaml`: @@ -31,14 +31,10 @@ and then connect it to the service by specifying it in the `compose.yaml`: ```yaml services: my-service: - secrets: + environment: - MY_API_KEY - -secrets: - MY_API_KEY: - external: true ``` -:::info Configuration & Secrets -Read more about configuration in the [configuration page](./configuration.md). +:::info +Read more about configuration in the [Configuration page](./configuration.md). ::: diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 0b5076e2d..8663822ad 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -8,7 +8,7 @@ sidebar_position: 225 Defang allows you to configure your application using environment variables. You can set environment variables in your [`compose.yaml` file](./compose.md), or in your [Pulumi program](#using-config-with-pulumi). -# Sensitive Config (aka Secrets) +# Sensitive Config Values The Defang CLI allows you to securely store sensitive information such as API keys, passwords, and other credentials. To do so, run: @@ -47,7 +47,7 @@ You can find a sample of how to set sensitive config values [here](https://githu ## Interpolation -Environment variables are set within the *environment* section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container. +Environment variables are set within the `environment` section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container. Variables can be set by assigning a literal value, a reference to a configuration value, or a mix of literal and variable references. Variable references are declared using either **\$\{variable_name\}** or **$variable_name** forms. It is recommended to use the bracketed form. By interpolating over variable references within a string we can construct complex strings. Interpolation may be particularly useful when constructing connection strings to other services. @@ -82,5 +82,6 @@ Here are the different ways sensitive config values are stored depending on the * [DigitalOcean](../providers/digitalocean#secrets) * [GCP](../providers/gcp#secrets) - - +:::info +Please note that while Defang supports setting sensitive config, it does not support the [`secrets`](https://docs.docker.com/reference/compose-file/secrets/) top-level element as seen in the Compose specification. Please see our [Compose Support](/docs/concepts/compose-support) page for more details. +::: From 823b11d725cb017d321dac771eec8d4d1b167dc4 Mon Sep 17 00:00:00 2001 From: commit111 Date: Fri, 27 Dec 2024 14:16:25 -0800 Subject: [PATCH 5/6] better wording for tutorial --- docs/tutorials/configure-environment-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/configure-environment-variables.md b/docs/tutorials/configure-environment-variables.md index 2511a98e0..46c3d94b3 100644 --- a/docs/tutorials/configure-environment-variables.md +++ b/docs/tutorials/configure-environment-variables.md @@ -16,7 +16,7 @@ This tutorial will show you how to configure sensitive environment variables in ## Step 1 - Go to your `compose.yaml` file :::info -If you are using [Pulumi](/docs/concepts/pulumi) instead of Compose files to define your application, please see [Using Config With Pulumi](/docs/concepts/configuration#using-config-with-pulumi). +If you are using [Pulumi](/docs/concepts/pulumi) instead of Compose files to define your services, please see [Using Config With Pulumi](/docs/concepts/configuration#using-config-with-pulumi) instead. ::: In your Compose file, you can define a sensitive config variable for your service by leaving it as a **blank or `null` value**. Defang will recognize it as a sensitive value. @@ -48,7 +48,7 @@ defang config set API_KEY=actualvalue Remember to replace `API_KEY` with your variable name and `actualvalue` with your actual value. :::tip -You can view all of your config variables by doing `defang config ls`. +You can view all the config variables you are storing in Defang by doing: `defang config ls`. ::: ### Editing a config value From e087330e4b473106a81491c5edae95258703eb39 Mon Sep 17 00:00:00 2001 From: commit111 Date: Fri, 27 Dec 2024 14:29:11 -0800 Subject: [PATCH 6/6] remove ref to compose-support for now --- docs/concepts/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 8663822ad..be57b983f 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -83,5 +83,5 @@ Here are the different ways sensitive config values are stored depending on the * [GCP](../providers/gcp#secrets) :::info -Please note that while Defang supports setting sensitive config, it does not support the [`secrets`](https://docs.docker.com/reference/compose-file/secrets/) top-level element as seen in the Compose specification. Please see our [Compose Support](/docs/concepts/compose-support) page for more details. +Please note that while Defang supports setting sensitive config, it does not support the [`secrets`](https://docs.docker.com/reference/compose-file/secrets/) top-level element as seen in the Compose specification. Please see our [Compose](/docs/concepts/compose) page for more details. :::