Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add 'iam_alias' and 'gce_alias' fields to API docs #8822

Merged
merged 1 commit into from
Apr 27, 2020
Merged

Add 'iam_alias' and 'gce_alias' fields to API docs #8822

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions website/pages/api-docs/auth/gcp/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,11 @@ The following parameters are only valid when the role is of type `"iam"`:
allow GCE instances to authenticate by inferring service accounts from the
GCE identity metadata token.

- `iam_alias` `(string: unique_id)` - Must be either `unique_id` or `role_id`.
If `unique_id` is specified, the service account's unique ID will be used for
alias names. If `role_id` is specified, the ID of the Vault role will be used.
Only used if `type` is `iam`.

#### `gce`-only Parameters

The following parameters are only valid when the role is of type `"gce"`:
Expand All @@ -164,6 +169,11 @@ The following parameters are only valid when the role is of type `"gce"`:
GCP labels are not currently ACL'd, we recommend that this be used in
conjunction with other restrictions.

- `gce_alias` `(string: instance_id)` - Must be either `instance_id` or `role_id`.
If `instance_id` is specified, the GCE instance ID will be used for alias names.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the performance implications of using instance_id be mentioned? Something like "Many unique GCE instances over time can cause severe performance issues on authentication that can also affect the reliability of Vault."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm torn on whether to do this, mainly because the performance issue comes when you have an alias, and its metadata fields change a lot. There's further discussion of it in this PR: #8783. I'm going to do a quick follow-on PR adding the ability to configure what metadata fields are used as well, and I'd be happy to document which are riskier for each alias as part of it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I lean away from mentioning performance implications because it is very use-case dependent. If we do add any notes about performance, I think it would be better to include it in @tyrannosaurus-becks 's follow on PR for configuring metadata.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We observed large numbers of entities created with aliases that have unique names and no metadata as well. In this case, the name includes the instance id which is unique, so a new entity will be created for every GCE instance over time.

If `role_id` is specified, the ID of the Vault role will be used. Only used if
`type` is `gce`.

### Sample Payload

Example `iam` role:
Expand Down Expand Up @@ -316,9 +326,11 @@ $ curl \
},
"bound_service_accounts": ["[email protected]"],
"bound_zones": ["eu-west2-a", "us-east1-b"],
"gce_alias": "instance_id",
"max_ttl": 86400,
"policies": ["prod"],
"project_id": "project-123456",
"role_id": "6bbfab2b-ca32-6044-4829-4515728d87b1",
"type": "gce",
"ttl": 1800
}
Expand Down