Update README with options

2021-09-30 09:35:19 -07:00
1 parent a934f88f54
commit d74ed15bdc
@@ -13,5 +13,84 @@ plugin is performed via the attribute/secret values passed to the create or
 update calls actions. These values are input as JSON objects; the expected types
 are indicated below with the valid fields.

-This plugin is currently in heavy development! A more formal README and
-documentation will follow soon.
+The plugin fetches hosts through the
+[DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html)
+call.
+
+## Credential Rotation
+
+Although credentials are stored encrypted within Boundary, by default this
+plugin will attempt to rotate credentials when they are supplied through the
+`secrets` object on a create or update call to the host catalog resource. The
+given credentials will be used to create a new credential, and then the given
+credential will be revoked. In this way, after rotation, only Boundary knows the
+client secret in use by this plugin.
+
+## Required IAM Privileges
+
+The following IAM privileges, at the very least, is required to be attached to a
+configured IAM user for this provider:
+
+* `ec2:DescribeInstances`, configured to `*` (`DescribeInstances` cannot be
+  scoped to a resource ARN). Example policy:
+
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "ec2:DescribeInstances"
+      ],
+      "Effect": "Allow",
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+* `iam:GetUser`, `iam:CreateAccessKey`, and `iam:DeleteAccessKey`, configured to
+  the set IAM user to allow credential rotation. Example policy:
+
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "iam:DeleteAccessKey",
+        "iam:GetUser",
+        "iam:CreateAccessKey"
+      ],
+      "Effect": "Allow",
+      "Resource": "arn:aws:iam::123456789012:user/JohnDoe"
+    }
+  ]
+}
+```
+
+## Attributes and Secrets
+
+### Host Catalog
+
+The following `attributes` are valid on an Azure host catalog resource:
+
+- `disable_credential_rotation` (bool): If `true`, credential rotation will not
+  be performed. See the Credential Rotation section above.
+- `region` (string): The region to configure the host catalog for. All host sets
+  in this catalog will be configured for this region.
+
+The following `secrets` are valid on an Azure host catalog resource:
+
+- `access_key_id` (string): The access key ID for the IAM user to use with this
+  host catalog.
+- `secret_access_key` (string): The secret access key for the IAM user to use
+  with this host catalog.
+
+### Host Set
+
+The following attributes are valid on an Azure host Set resource:
+
+- `filters` (string): An object of filters to filter off of. For a list of
+  filter options, check out [describe-instances in the AWS CLI
+  reference](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).