docs(DVT): Add config.yaml doc and update CLi doc MTA-4434 (#3102)

* docs(DVT): Add config.yaml doc and update CLi doc MTA-4434 * docs(DVT): update * docs(DVT): update
scaleway · Apr 23, 2024 · 8b610ca · 8b610ca
1 parent 220e132
commit 8b610ca
Show file tree

Hide file tree

Showing 9 changed files with 204 additions and 22 deletions.
diff --git a/developer-tools/scaleway-cli/reference-content/environment-variables.mdx b/developer-tools/scaleway-cli/reference-content/environment-variables.mdx
@@ -1,9 +1,9 @@
 ---
 meta:
-  title: Scaleway environment variables
-  description: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
+  title: Scaleway CLI - environment variables
+  description: This page contains a list of standardized environment variables used throughout the Scaleway CLI and other developer tools.
 content:
-  h1: Scaleway environment variables
+  h1: Scaleway CLI - environment variables
   paragraph: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
 tags: devtools cli api variables
 dates:

diff --git a/developer-tools/scaleway-cli/reference-content/scaleway-configuration-file.mdx b/developer-tools/scaleway-cli/reference-content/scaleway-configuration-file.mdx
@@ -0,0 +1,16 @@
+---
+meta:
+  title: Scaleway CLI - Configuration file
+  description: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+content:
+  h1: Scaleway CLI - Configuration file
+  paragraph: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+tags: developer tools cli configuration config
+dates:
+  validation: 2024-04-23
+  posted: 2023-04-23
+categories:
+  - devtools
+---
+
+<Macro id="scaleway-configuration-file" />
diff --git a/developer-tools/scaleway-sdk/reference-content/environment-variables.mdx b/developer-tools/scaleway-sdk/reference-content/environment-variables.mdx
@@ -0,0 +1,16 @@
+---
+meta:
+  title: Scaleway SDKs - environment variables
+  description: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
+content:
+  h1: Scaleway SDKs - environment variables
+  paragraph: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
+tags: devtools cli api variables
+dates:
+  validation: 2024-04-03
+  posted: 2023-05-15
+categories:
+  - devtools
+---
+
+<Macro id="scaleway-environment-variables" />
diff --git a/developer-tools/scaleway-sdk/reference-content/scaleway-configuration-file.mdx b/developer-tools/scaleway-sdk/reference-content/scaleway-configuration-file.mdx
@@ -0,0 +1,16 @@
+---
+meta:
+  title: Scaleway SDKs - Configuration file
+  description: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+content:
+  h1: Scaleway SDKs - Configuration file
+  paragraph: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+tags: developer tools cli configuration config sdk
+dates:
+  validation: 2024-04-23
+  posted: 2023-04-23
+categories:
+  - devtools
+---
+
+<Macro id="scaleway-configuration-file" />
diff --git a/developer-tools/terraform/reference-content/environment-variables.mdx b/developer-tools/terraform/reference-content/environment-variables.mdx
@@ -1,11 +1,11 @@
 ---
 meta:
-  title: Scaleway environment variables
+  title: Terraform - Scaleway environment variables
   description: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
 content:
-  h1: Scaleway environment variables
+  h1: Terraform - Scaleway environment variables
   paragraph: This page contains a list of standardized environment variables used throughout the Scaleway developer tools.
-tags: devtools cli api variables
+tags: devtools cli api variables terraform
 dates:
   validation: 2024-04-03
   posted: 2023-05-24

diff --git a/developer-tools/terraform/reference-content/scaleway-configuration-file.mdx b/developer-tools/terraform/reference-content/scaleway-configuration-file.mdx
@@ -0,0 +1,16 @@
+---
+meta:
+  title: Terraform - Scaleway Configuration file
+  description: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+content:
+  h1: Terraform - Scaleway Configuration file
+  paragraph: This page explains what is the Scaleway configuration file for developer tools and how to use it.
+tags: developer tools cli api configuration config terraform
+dates:
+  validation: 2024-04-23
+  posted: 2023-04-23
+categories:
+  - devtools
+---
+
+<Macro id="scaleway-configuration-file" />
diff --git a/macros/developer-tools/scaleway-configuration-file.mdx b/macros/developer-tools/scaleway-configuration-file.mdx
@@ -0,0 +1,109 @@
+---
+macro: scaleway-configuration-file
+---
+
+## Configuration file Overview
+
+The Scaleway configuration file is a `config.yaml` file shared between the majority of the [Scaleway developer tools](https://www.scaleway.com/en/developers/#official-repos). It allows you to authenticate, and to determine the default values to use when creating resources with the developer tools.
+
+The configuration file contains the following elements:
+
+**access_key**
+: Your [Scaleway API access key](/identity-and-access-management/iam/how-to/create-api-keys/)
+
+**secret_key**
+: Your [Scaleway API secret key](/identity-and-access-management/iam/how-to/create-api-keys/)
+
+**default_organization_id**
+: The ID of the Scaleway Organization to use by default
+
+**default_project_id**
+: The ID of the Scaleway Project to use by default
+
+**default_zone**
+: The [availability zone](console/account/reference-content/products-availability/) to use by default
+
+**default_region**
+: The [region](console/account/reference-content/products-availability/) to use by default
+
+**api_url**
+: The API URL to use (`https://api.scaleway.com` by default)
+
+**insecure**
+: Parameter to allow insecure traffic on the client (`false` by default)
+
+**send-telemetry**
+: Parameter to disable the collection of diagnostic and usage data (`true` by default)
+
+**profiles**
+: A YAML dictionary that can contain different profiles (refer to the [example](macros/developer-tools/scaleway-configuration-file/#multi-profile-configuration-file) below)
+
+## How to set up the configuration file
+
+You can set up the Scaleway configuration file using several methods. However, we recommend that you use [The Scaleway CLI](/developer-tools/scaleway-cli/quickstart/). The `scw init` command allows you to initialize your configuration in just a few minutes.
+
+To initialize the configuration without the Scaleway CLI, you can simply create a `config.yaml` file in the appropriate folder:
+
+    - a **custom directory** defined as `$SCW_CONFIG_PATH`
+
+    - an **XDG** base directory: `$XDG_CONFIG_HOME/scw/config.yaml`
+
+    - the **MacOS/Linux** home directory: `$HOME/.config/scw/config.yaml`
+
+    - the **Windows** home directory: `%USERPROFILE%/.config/scw/config.yaml`
+
+## Configuration file example
+
+### Single profile configuration file
+
+```yaml
+access_key: EXAMPLESCW34P0XKFD4
+secret_key: example-2b41-8d52-f888-8c8a460e
+default_organization_id: example-468g-4f65-a41e-8b40766c5fc5
+default_project_id: example-468g-4f65-a41e-8b40766c5fc5
+default_zone: fr-par-1
+default_region: fr-par
+api_url: https://api.scaleway.com
+```
+
+### Multi-profile configuration file
+
+```yaml
+profiles:
+  myProfile1:
+    access_key: EXAMPLESCW34P0XKFD4
+    secret_key: example-2b41-8d52-f888-8c8a460e
+    default_organization_id: example-468g-4f65-a41e-8b40766c5fc5
+    default_project_id: example-468g-4f65-a41e-8b40766c5fc5
+    default_zone: fr-par-1
+    default_region: fr-par
+    api_url: https://api.scaleway.com
+    insecure: false
+
+  myProfile2:
+    access_key: EXAMPLESCW34PM3C0XK
+    secret_key: example-2b41-460e-8d52-f8888c8a
+    default_organization_id: example-776f-4f65-a41e-6c5fc58b4076
+    default_project_id: example-776f-4f65-a41e-6c5fc58b4076
+    default_zone: fr-par-2
+    default_region: fr-par
+    api_url: https://api.scaleway.com
+    insecure: true
+```
+
+<Message type="note">
+You can select the profile to use by either:
+- declaring it as the `$SCW_PROFILE` environment variable
+- using the `GetActiveProfile()` function in the SDKs
+- use the `--profile=<your-profile>` flag with the CLI
+</Message>
+
+## Troubleshooting
+
+- Make sure that you have generated and specified a valid `access_key` and `secret_key` pair. Refer to the [API keys](/identity-and-access-management/iam/how-to/create-api-keys/) documentation for more information.
+
+- Make sure that there is no conflicting environment variable set, such as `$SCW_ACCESS_KEY` and `$SCW_SECRET_KEY`. You can remove environment variables using the `unset` command as shown below:
+
+  ```bash
+  unset $SCW_ACCESS_KEY $SCW_SECRET_KEY
+  ```
diff --git a/macros/developer-tools/scaleway-environment-variables.mdx b/macros/developer-tools/scaleway-environment-variables.mdx
@@ -15,16 +15,3 @@ The following standardized Scaleway environment variables are used for the CLI a
 | `$SCW_PROFILE`                 | Set the configuration profile to use                                                             | -                                                                                                             |
 | `$SCW_PROJECT_ID`              | Your [Project ID](https://console.scaleway.com/project/settings) | `$SCW_DEFAULT_PROJECT_ID`                                                                                     |
 | `$SCW_ORGANIZATION_ID`         | Your [Organization ID](https://console.scaleway.com/organization/settings) | `$SCW_DEFAULT_ORGANIZATION_ID`, `$SCW_ORGANIZATION` (used by the CLI),`$SCALEWAY_ORGANIZATION` (used by Terraform) |
-
-## Recommended Scaleway configuration file
-
-Your configuration file should at least contain the following values to be fully compatible with all developer tools:
-
-```yaml
-SCW_ACCESS_KEY: SCWXXXXXXXXXXXXXXXXX
-SCW_SECRET_KEY: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-SCW_ORGANIZATION_ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-SCW_PROJECT_ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-SCW_DEFAULT_ZONE: fr-par
-SCW_DEFAULT_REGION: fr-par-1
-```
diff --git a/menu/navigation.json b/menu/navigation.json
@@ -3529,6 +3529,10 @@
                   {
                     "label": "Environment variables",
                     "slug": "environment-variables"
+                  },
+                  {
+                    "label": "Scaleway Configuration file",
+                    "slug": "scaleway-configuration-file"
                   }
                 ],
                 "label": "Additional Content",
@@ -3541,16 +3545,30 @@
           {
             "items": [
               {
-                "label": "Python SDK",
+                "label": "Python SDK quickstart",
                 "slug": "python-sdk"
               },
               {
-                "label": "Go SDK",
+                "label": "Go SDK quickstart",
                 "slug": "go-sdk"
               },
               {
-                "label": "JavaScript SDK",
+                "label": "JavaScript SDK quickstart",
                 "slug": "js-sdk"
+              },
+              {
+                "items": [
+                  {
+                    "label": "Environment variables",
+                    "slug": "environment-variables"
+                  },
+                  {
+                    "label": "Scaleway Configuration file",
+                    "slug": "scaleway-configuration-file"
+                  }
+                ],
+                "label": "Additional Content",
+                "slug": "reference-content"
               }
             ],
             "label": "Scaleway SDKs",
@@ -3567,6 +3585,10 @@
                   {
                     "label": "Environment variables",
                     "slug": "environment-variables"
+                  },
+                  {
+                    "label": "Scaleway Configuration file",
+                    "slug": "scaleway-configuration-file"
                   }
                 ],
                 "label": "Additional Content",