Skip to content

Commit e4167ed

Browse files
authored
Update guides (#180)
1 parent 43e2acd commit e4167ed

File tree

10 files changed

+254
-106
lines changed

10 files changed

+254
-106
lines changed

docs/data-sources/aws_cnp_artifacts.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ data "polaris_aws_cnp_artifacts" "artifacts" {
8989
permission_groups = [
9090
"BASIC",
9191
"EXPORT_AND_RESTORE",
92-
"EXPORT_AND_RESTORE",
92+
"FILE_LEVEL_RECOVERY",
9393
]
9494
}
9595
}

docs/data-sources/aws_cnp_permissions.md

-1
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,6 @@ data "polaris_aws_cnp_artifacts" "artifacts" {
122122
# artifacts data source.
123123
data "polaris_aws_cnp_permissions" "permissions" {
124124
for_each = data.polaris_aws_cnp_artifacts.artifacts.role_keys
125-
126125
cloud = data.polaris_aws_cnp_artifacts.artifacts.cloud
127126
role_key = each.key
128127

docs/guides/aws_cnp_account.md

+41-17
Original file line numberDiff line numberDiff line change
@@ -7,58 +7,82 @@ The `polaris_aws_account` resource uses a CloudFormation stack to grant RSC perm
77
granted to RSC by the CloudFormation stack can be difficult to understand and track as RSC will request the permissions
88
to be updated as new features, requiring new permissions, are released.
99

10-
To make the process of granting AWS permissions more transparent, a couple of new resources and data sources have been added to
11-
the RSC Terraform provider:
10+
To make the process of granting AWS permissions more transparent, a couple of new resources and data sources have been
11+
added to the RSC Terraform provider:
1212
* `polaris_aws_cnp_account`
1313
* `polaris_aws_cnp_account_attachments`
1414
* `polaris_aws_cnp_account_trust_policy`
1515
* `polaris_aws_cnp_artifacts`
1616
* `polaris_aws_cnp_permissions`
17-
* `polaris_features`
17+
* `polaris_account`
1818

1919
Using these resources, it's possible to add an AWS account to RSC without using a CloudFormation stack.
2020

2121
To add an AWS account to RSC using the new CNP resources, start by using the `polaris_aws_cnp_artifacts` data source:
2222
```terraform
2323
data "polaris_aws_cnp_artifacts" "artifacts" {
24-
features = ["CLOUD_NATIVE_PROTECTION"]
24+
feature {
25+
name = "CLOUD_NATIVE_PROTECTION"
26+
27+
permission_groups = [
28+
"BASIC",
29+
"EXPORT_AND_RESTORE",
30+
"FILE_LEVEL_RECOVERY",
31+
"SNAPSHOT_PRIVATE_ACCESS",
32+
]
33+
}
2534
}
2635
```
27-
`features` lists the RSC features to enabled for the AWS account. Use the `polaris_features` data source to obtain a
28-
list of RSC features available for the RSC account. The `polaris_aws_cnp_artifacts` data source returns the instance
29-
profiles and roles, referred to as _artifacts_ by RSC, which are required by RSC.
36+
One or more `feature` blocks lists the RSC features to enabled for the AWS account. Use the `polaris_account` data
37+
source to obtain a list of RSC features available for the RSC account. The `polaris_aws_cnp_artifacts` data source
38+
returns the instance profiles and roles, referred to as _artifacts_ by RSC, which are required by RSC.
3039

3140
Next, use the `polaris_aws_cnp_permissions` data source to obtain the role permission policies, customer managed
3241
policies and managed policies, required by RSC:
3342
```terraform
3443
data "polaris_aws_cnp_permissions" "permissions" {
3544
for_each = data.polaris_aws_cnp_artifacts.artifacts.role_keys
36-
features = data.polaris_aws_cnp_artifacts.artifacts.features
3745
role_key = each.key
46+
47+
dynamic "feature" {
48+
for_each = data.polaris_aws_cnp_artifacts.artifacts.feature
49+
content {
50+
name = feature.value["name"]
51+
permission_groups = feature.value["permission_groups"]
52+
}
53+
}
3854
}
3955
```
4056

4157
After defining the two data sources, use the `polaris_aws_cnp_account` resource to start the onboarding of the AWS
4258
account:
4359
```terraform
4460
resource "polaris_aws_cnp_account" "account" {
45-
features = polaris_aws_cnp_artifacts.artifacts.features
4661
name = "My Account"
4762
native_id = "123456789123"
4863
regions = ["us-east-2", "us-west-2"]
64+
65+
dynamic "feature" {
66+
for_each = polaris_aws_cnp_artifacts.artifacts.features
67+
content {
68+
name = feature.value["name"]
69+
permission_groups = feature.value["permission_groups"]
70+
}
71+
}
4972
}
5073
```
51-
`name` is the name given to the AWS account in RSC, `native_id` is the AWS account ID and `regions` the AWS regions.
52-
When Terraform processes this resource, the AWS account will show up in the connecting state in the RSC UI.
74+
`name` is the name given to the AWS account in RSC, `native_id` is the AWS account ID and `regions` the AWS regions to
75+
protect with RSC. When Terraform processes this resource, the AWS account will show up in the connecting state in the
76+
RSC UI.
5377

5478
Next, the `polaris_aws_cnp_account_trust_policy` resource needs to be used to define the trust policies required by RSC
5579
for the AWS account:
5680
```terraform
5781
resource "polaris_aws_cnp_account_trust_policy" "trust_policy" {
58-
for_each = data.polaris_aws_cnp_artifacts.artifacts.role_keys
59-
account_id = polaris_aws_cnp_account.account.id
60-
features = polaris_aws_cnp_account.account.features
61-
role_key = each.key
82+
for_each = data.polaris_aws_cnp_artifacts.artifacts.role_keys
83+
account_id = polaris_aws_cnp_account.account.id
84+
features = polaris_aws_cnp_account.account.feature.*.name
85+
role_key = each.key
6286
}
6387
```
6488
This resource provides the trust policies to attach to the IAM roles created, so that RSC can assume the roles to
@@ -95,13 +119,13 @@ Lastly, to finalize the onboarding of the AWS account, use the `polaris_aws_cnp_
95119
```terraform
96120
resource "polaris_aws_cnp_account_attachments" "attachments" {
97121
account_id = polaris_aws_cnp_account.account.id
98-
features = polaris_aws_cnp_account.account.features
122+
features = polaris_aws_cnp_account.account.feature.*.name
99123
100124
dynamic "instance_profile" {
101125
for_each = aws_iam_instance_profile.profile
102126
content {
103127
key = instance_profile.key
104-
name = instance_profile.value["name"]
128+
name = instance_profile.value["arn"]
105129
}
106130
}
107131

docs/guides/changelog.md

+4
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ page_title: "Changelog"
44

55
# Changelog
66

7+
## v0.9.0-beta.8
8+
* Improve the documentation for AWS data sources and resources.
9+
* Update guides.
10+
711
## v0.9.0-beta.7
812
* Add `polaris_azure_archival_location` data source. [[docs](../data-sources/azure_archival_location)]
913
* Fix a bug in the `polaris_azure_archival_location` resource where the cloud account UUID would be passed to the RSC

docs/guides/permissions.md

+81-34
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,14 @@ RSC requires permissions to operate and as new features are added to RSC the set
77
guide explains how Terraform can be used to keep this set of permissions up to date.
88

99
## AWS
10-
For AWS this is managed through a CloudFormation stack. When the status of an account feature is `missing-permissions`
11-
the CloudFormation stack must be updated for the feature to continue to function. This can be managed by setting the
12-
`permissions` argument to `update`.
13-
```hcl
10+
There are two ways to onboard AWS accounts to RSC, using a CloudFormation stack or not. Depending on the way an account
11+
is onboarded, permissions are managed in different ways.
12+
13+
### Using a CloudFormation Stack
14+
When an account is onboarded using a CloudFormation stack, the permissions are managed through the stack. When the
15+
status of an account feature is `MISSING_PERMISSIONS` the CloudFormation stack must be updated for the RSC feature to
16+
continue to function. This can be managed by setting the `permissions` argument to `update`.
17+
```terraform
1418
resource "polaris_aws_account" "default" {
1519
profile = "default"
1620
permissions = "update"
@@ -22,55 +26,98 @@ resource "polaris_aws_account" "default" {
2226
}
2327
}
2428
```
25-
This will generate a diff when the status of at least one feature is `missing-permissions`. Applying the account
26-
resource for this diff will update the CloudFormation stack. If the `permissions` argument is not specified the
29+
This will generate a diff when the status of at least one feature is in the `MISSING_PERMISSIONS` state. Applying the
30+
account resource for this diff will update the CloudFormation stack. If the `permissions` argument is not specified the
2731
provider will not attempt to update the CloudFormation stack.
2832

33+
### Not Using a CloudFormation Stack
34+
When an account is onboarded without using a CloudFormation stack, the permissions can be managed using the
35+
`polaris_aws_cnp_artifacts` and `polaris_aws_cnp_permissions` data sources and the
36+
[aws](https://registry.terraform.io/providers/hashicorp/aws/latest) provider, using IAM roles. Please see the
37+
[AWS CNP Account](aws_cnp_account.md) guide for more information on how create IAM roles using the data sources.
38+
2939
## Azure
30-
For Azure permissions are managed through a service principal. When the status of a subscription feature is
31-
`missing-permissions` the permissions of the service principal must be updated for the feature to continue to
32-
function. This can be managed by Terraform using the
33-
[azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest) provider:
34-
```hcl
35-
data "polaris_azure_permissions" "default" {
36-
features = [
37-
"cloud-native-protection",
38-
"exocompute",
39-
]
40+
For Azure permissions are managed through the subscription. When the status of a subscription feature is
41+
`MISSING_PERMISSIONS` the permissions must be updated for the feature to continue to function. This can be managed by
42+
Terraform using the [azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest) provider:
43+
```terraform
44+
variable "features" {
45+
type = set(string)
46+
description = "List of RSC features to enable for subscription."
47+
}
48+
49+
data "polaris_azure_permissions" "features" {
50+
for_each = var.features
51+
feature = each.key
4052
}
4153
42-
resource "azurerm_role_definition" "default" {
43-
name = "terraform"
44-
scope = data.azurerm_subscription.default.id
54+
resource "azurerm_role_definition" "subscription" {
55+
for_each = data.polaris_azure_permissions.features
56+
name = "RSC - Subscription Level - ${each.value.feature}"
57+
scope = data.azurerm_subscription.subscription.id
4558
4659
permissions {
47-
actions = data.polaris_azure_permissions.default.actions
48-
data_actions = data.polaris_azure_permissions.default.data_actions
49-
not_actions = data.polaris_azure_permissions.default.not_actions
50-
not_data_actions = data.polaris_azure_permissions.default.not_data_actions
60+
actions = each.value.subscription_actions
61+
data_actions = each.value.subscription_data_actions
62+
not_actions = each.value.subscription_not_actions
63+
not_data_actions = each.value.subscription_not_data_actions
5164
}
5265
}
5366
54-
resource "azurerm_role_assignment" "default" {
67+
resource "azurerm_role_assignment" "subscription" {
68+
for_each = data.polaris_azure_permissions.features
5569
principal_id = "9e7f3952-1fc1-11ec-b57a-972144d12d97"
56-
role_definition_id = azurerm_role_definition.default.role_definition_resource_id
57-
scope = data.azurerm_subscription.default.id
70+
role_definition_id = azurerm_role_definition.subscription[each.key].role_definition_resource_id
71+
scope = data.azurerm_subscription.subscription.id
5872
}
5973
60-
resource "polaris_azure_service_principal" "default" {
61-
sdk_auth = "${path.module}/sdk-service-principal.json"
62-
tenant_domain = "mydomain.onmicrosoft.com"
63-
permissions_hash = data.polaris_azure_permissions.default.hash
74+
resource "azurerm_role_definition" "resource_group" {
75+
for_each = data.polaris_azure_permissions.features
76+
name = "RSC - Resource Group Level - ${each.value.feature}"
77+
scope = data.azurerm_resource_group.resource_group.id
78+
79+
permissions {
80+
actions = each.value.resource_group_actions
81+
data_actions = each.value.resource_group_data_actions
82+
not_actions = each.value.resource_group_not_actions
83+
not_data_actions = each.value.resource_group_not_data_actions
84+
}
85+
}
86+
87+
resource "azurerm_role_assignment" "resource_group" {
88+
for_each = data.polaris_azure_permissions.features
89+
principal_id = "9e7f3952-1fc1-11ec-b57a-972144d12d97"
90+
role_definition_id = azurerm_role_definition.resource_group[each.key].role_definition_resource_id
91+
scope = data.azurerm_resource_group.resource_group.id
92+
}
93+
94+
resource "polaris_azure_service_principal" "service_principal" {
95+
...
96+
}
97+
98+
resource "polaris_azure_subscription" "subscription" {
99+
subscription_id = data.azurerm_subscription.subscription.subscription_id
100+
subscription_name = data.azurerm_subscription.subscription.display_name
101+
tenant_domain = polaris_azure_service_principal.service_principal.tenant_domain
102+
103+
cloud_native_protection {
104+
permissions = data.polaris_azure_permissions.features["CLOUD_NATIVE_PROTECTION"].id
105+
resource_group_name = data.azurerm_resource_group.resource_group.name
106+
resource_group_region = data.azurerm_resource_group.resource_group.location
107+
regions = ["eastus2"]
108+
}
109+
110+
...
64111
65112
depends_on = [
66-
azurerm_role_definition.default,
67-
azurerm_role_assignment.default,
113+
azurerm_role_definition.subscription,
114+
azurerm_role_definition.resource_group,
68115
]
69116
}
70117
```
71118
When the permissions for a feature changes the permissions data source will reflect this generating a diff for the
72-
role definition and service principal resources. Applying the diff will first update the permissions of the service
73-
principal's role definition and then notify RSC about the update.
119+
role definitions and subscription resources. Applying the diff will first update the permissions of the role
120+
definitions, then notify RSC about the update.
74121

75122
## GCP
76123
For GCP permissions are managed through a service account. When the status of a project feature is `missing-permissions`

examples/data-sources/polaris_aws_cnp_artifacts/data-source.tf

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ data "polaris_aws_cnp_artifacts" "artifacts" {
1414
permission_groups = [
1515
"BASIC",
1616
"EXPORT_AND_RESTORE",
17-
"EXPORT_AND_RESTORE",
17+
"FILE_LEVEL_RECOVERY",
1818
]
1919
}
2020
}

examples/data-sources/polaris_aws_cnp_permissions/data-source.tf

-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ data "polaris_aws_cnp_artifacts" "artifacts" {
2929
# artifacts data source.
3030
data "polaris_aws_cnp_permissions" "permissions" {
3131
for_each = data.polaris_aws_cnp_artifacts.artifacts.role_keys
32-
3332
cloud = data.polaris_aws_cnp_artifacts.artifacts.cloud
3433
role_key = each.key
3534

0 commit comments

Comments
 (0)