backport of commit 60d7051

website/content/api-docs/system/activation-flags.mdx

@@ -0,0 +1,92 @@
+---
+layout: api
+page_title: /sys/activation-flags - HTTP API
+description: The `/sys/activation-flags` endpoints are used to enable features that are gated by a one-time flag.
+---
+
+# `/sys/activation-flags`
+
+@include 'alerts/restricted-root.mdx'
+
+Use the `/sys/activation-flags` endpoints to read and manage Vault
+features that are gated by one-time flags. Gated features are
+blocked and return errors until activated. Once removed, you cannot
+un-activate gated features.
+
+## ReadActivationFlags
+
+ReadActivationFlags is an unauthenticated endpoint that returns information
+about gated features and their activation status as two lists: `activated` and
+`unactivated`. The activated list contains features ready to be used. The
+unactivated list contains **available** but gated features. It filters out those
+which are already active within your Vault instance.
+
+| Method | Path                    |
+| :----- | :---------------------- |
+| `GET`  | `/sys/activation-flags` |
+
+### Sample request
+
+```shell-session
+$ curl \
+    --request GET \
+    http://127.0.0.1:8200/v1/sys/activation-flags
+```
+
+### Sample response
+
+```json
+{
+    "request_id": "9f70548c-a039-24a6-147d-7fa43698e044",
+    "lease_id": "",
+    "lease_duration": 0,
+    "renewable": false,
+    "data": {
+        "activated": [],
+        "unactivated": [
+            "secrets-sync"
+        ]
+    },
+    "warnings": null
+}
+```
+
+## WriteActivationFlags
+
+WriteActivationFlags unblocks and enables gated Vault features.
+
+| Method | Path                                      |
+| :----- | :---------------------------------------- |
+| `PUT`  | `/sys/activation-flags/:feature/activate` |
+
+### URL parameters
+
+- `feature` `(string: <required>)` Feature key from ReadActivationFlags indicating the feature to activate.
+
+### Sample request
+
+```shell-session
+$ curl \
+    --request PUT \
+    --header "X-Vault-Token: $VAULT_TOKEN" \
+    http://127.0.0.1:8200/v1/sys/activation-flags/secrets-sync/activate
+```
+
+### Sample response
+
+```json
+{
+    "request_id": "7636e655-e11d-e2aa-8286-bd38c1d9c600",
+    "lease_id": "",
+    "lease_duration": 0,
+    "renewable": false,
+    "data": {
+        "activated": [
+            "secrets-sync"
+        ],
+        "unactivated": []
+    },
+    "warnings": null,
+    "mount_type": "system"
+}
+```

website/content/api-docs/system/secrets-sync.mdx

@@ -381,11 +381,14 @@ This endpoint creates a destination to synchronize secrets with the GCP Secret M
 - `credentials` `(string: <required>)` - JSON credentials (either file contents or '@path/to/file')
 See docs for [alternative ways](/vault/docs/secrets/gcp#authentication) to pass in to this parameter
 
-- `project_id` `(string: <optional>)` - The target project to manage secrets in. If set,
+- `project_id` `(string: "")` - The target project to manage secrets in. If set,
   overrides the project ID derived from the service account JSON credentials or application
   default credentials. The service account must be [authorized](https://cloud.google.com/iam/docs/service-account-overview#locations)
   to perform Secret Manager actions in the target project.
 
+- `replication_locations` `(list: nil)` - A list of GCP location names the destination can use to
+store replicated secrets. Note that secrets remain globally readable regardless of the selected locations.
+
 - `secret_name_template` `(string: "")` - Template to use when generating the secret names on the external system.
 The default template yields names like `vault/kv_1234/my-secret`. See [this documentation](/vault/docs/sync#name-template) for more details.
 
@@ -398,7 +401,11 @@ destination. See [this documentation](/vault/docs/sync#granularity) for more det
 ### Sample payload
 ```json
 {
-    "credentials": "<JSON string>"
+    "credentials": "<private key string>",
+    "replication_locations": [
+        "us-east1",
+        "us-west1"
+    ]
 }
 ```
 
@@ -424,39 +431,88 @@ This endpoint creates a destination to synchronize action secrets with a GitHub
 
 - `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
 
-- `access_token` `(string: <optional>)` - Fine-grained or personal access token.
+- `secrets_location` `(string: "repository")` - The GitHub location type of secrets to sync. Must be either `organization` or `repository`.
+
+- `access_token` `(string: ""` - Fine-grained or personal access token.
   Use `access_token` as an alternative to authenticating with a GitHub app.
 
-- `app_name` `(string: <optional>)` - The name of a GitHub App configured in Vault to use for
+- `app_name` `(string: "")` - The name of a GitHub App configured in Vault to use for
   authentication. You can use `app_name` with `installation_id` 
   as authentication instead of an access token. Refer to the
   [Configure a custom GitHub app section](/vault/api-docs/system/secrets-sync#configure-a-custom-github-app)
   of the Secrets sync API docs for more information.
 
-  - `installation_id` `(string: <optional>)` - The installation ID of the GitHub
-  app to use for authentication. Required when using `app_name` for
-  authentication.
+  - `installation_id` `(string: "")` - The installation ID of the GitHub
+  app to use for authentication. Required when using `app_name` for authentication.
+
+- `repository_owner` `(string: "")` - GitHub owner of the secrets sync
+  target location when `secrets_location` is `repository`. For example, if the
+  target repository URL is `https://github.com/hashicorp/vault.git`, the owner
+  is `hashicorp`.
+
+  - `repository_name` `(string: "")` - GitHub repository name of the
+    secrets sync target location when `secrets_location` is `repository`. For
+    example, if the target repository URL is
+    `https://github.com/hashicorp/vault.git`, the repository name is `vault`.
+
+  - `environment_name` `(string: "")` - GitHub environment name of the secrets
+    sync target location when `secrets_location` is `repository`. By default,
+    secrets are global to the targeted repository.
 
-- `repository_owner` `(string: <required>)` - GitHub organization or username that owns the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the owner is hashicorp.
+- `organization_name` `(string: "")` - **(BETA)** GitHub organization
+  name of the secrets sync target location when `secrets_location` is
+  `organization`. For example, if the organization is
+  `https://github.com/hashicorp`, the organization name is `hashicorp`.
 
-- `repository_name` `(string: <required>)` - Name of the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the name is vault.
+  - `organization_visibility` `(string: "")` - **(BETA)** Controls which
+    repositories within the secrets sync target location can see synced secrets
+    when `secrets_location` is `organization`. Must be one of:
+    - `all` - all repositories can access synced secrets
+    - `private` - private and internal repositories can access synced secrets
+    - `selected` - repositories explicitly named in `selected_repository_names`
+      can access synced secrets.
 
-  - `environment_name` `(string: '')` - The name of a GitHub environment
-    within the repo specified by `repository_name`. By default, secrets are
-    global to the targeted repository. 
+  - `selected_repository_names` `(list: nil)` - **(BETA)** Explicit list of
+    repository names in the secrets sync target location that can access
+    synced secrets when `secrets_location` is `organization`.
 
 - `secret_name_template` `(string: "")` - Template to use when generating the secret names on the external system.
 The default template yields names like `VAULT_KV_1234_MY_SECRET`. See [this documentation](/vault/docs/sync#name-template) for more details.
 
 - `granularity` `(string: "secret-key")` - Determines what level of information is synced as a distinct resource at the
 destination. See [this documentation](/vault/docs/sync#granularity) for more details.
 
-### Sample payload
+## Example requests
+
+### Sync secrets to a GitHub repository
+```json
+{
+    "access_token": "github_pat_12345",
+    "secrets_location": "repository",
+    "repository_owner": "my-organization-or-username",
+    "repository_name": "my-repository",
+}
+```
+
+### Sync secrets to a GitHub environment
 ```json
 {
     "access_token": "github_pat_12345",
+    "secrets_location": "repository",
     "repository_owner": "my-organization-or-username",
-    "repository_name": "my-repository"
+    "repository_name": "my-repository",
+    "environment_name": "my-environment"
+}
+```
+
+### Sync secrets to a GitHub organization
+```json
+{
+    "access_token": "github_pat_12345",
+    "secrets_location": "organization",
+    "organization_name": "my-organization",
+    "organization_visibility": "selected",
+    "selected_repository_names": "my-repository-1,my-repository-2,my-repository-3"
 }
 ```
 

website/content/docs/sync/gcpsm.mdx

@@ -28,6 +28,7 @@ Prerequisites:
   ```shell-session
   $ vault write sys/sync/destinations/gcp-sm/my-dest \
       credentials='@path/to/credentials.json'
+      replication_locations='us-east1,us-west1'
   ```
 
   **Output:**
@@ -37,7 +38,7 @@ Prerequisites:
   ```plaintext
   Key                   Value
   ---                   -----
-  connection_details    map[credentials:*****]
+  connection_details    map[credentials:***** replication_locations:us-east1,us-west1]
   name                  my-dest
   type                  gcp-sm
   ```
@@ -117,6 +118,16 @@ Moving forward, any modification on the Vault secret will be propagated in near
 counterpart. Creating a new secret version in Vault will create a new version in GCP Secret Manager. Deleting the secret
 or the association in Vault will delete the secret in your GCP project as well.
 
+### Replication policy
+
+GCP can target specific geographic regions to provide strict control on where
+your applications store data and sync secrets. You can target specific GCP 
+regions for each sync destinations during creation which will limit where Vault writes 
+secrets. 
+
+Regardless of the region limits on writes, synced secrets are always readable 
+globally when the client has the required permissions.
+
 ## Permissions
 
 The credentials given to Vault must have the following permissions to synchronize secrets: