CSP Health Monitor - IAM Requirements

Overview

The CSP Health Monitor requires IAM permissions to monitor cloud provider maintenance events. This document provides the setup commands for GCP and AWS.

Google Cloud Platform (GCP)

Required IAM Permission

logging.logEntries.list - Read Cloud Logging entries for maintenance events

Setup Commands

Replace placeholders:

<GCP_SA_NAME> - GCP Service Account name (e.g., csp-health-monitor)
<TARGET_PROJECT_ID> - GCP project ID where the cluster runs
<GKE_PROJECT_ID> - GCP project ID where GKE cluster is deployed
<NAMESPACE> - Kubernetes namespace (default: nvsentinel)

$ # 1. Create GCP Service Account
$ gcloud iam service-accounts create &lt;GCP_SA_NAME> \
>     --display-name="CSP Health Monitor Service Account" \
>     --project=&lt;TARGET_PROJECT_ID>
$ 
$ # 2. Create custom IAM role with minimal permissions
$ gcloud iam roles create cspHealthMonitorRole \
>     --project=&lt;TARGET_PROJECT_ID> \
>     --title="CSP Health Monitor Role" \
>     --description="Minimal permissions for CSP Health Monitor" \
>     --permissions="logging.logEntries.list"
$ 
$ # 3. Grant role to GCP Service Account
$ gcloud projects add-iam-policy-binding &lt;TARGET_PROJECT_ID> \
>     --member="serviceAccount:&lt;GCP_SA_NAME>@&lt;TARGET_PROJECT_ID>.iam.gserviceaccount.com" \
>     --role="projects/&lt;TARGET_PROJECT_ID>/roles/cspHealthMonitorRole"
$ 
$ # 4. Enable Workload Identity binding
$ gcloud iam service-accounts add-iam-policy-binding \
>     &lt;GCP_SA_NAME>@&lt;TARGET_PROJECT_ID>.iam.gserviceaccount.com \
>     --role="roles/iam.workloadIdentityUser" \
>     --member="serviceAccount:&lt;GKE_PROJECT_ID>.svc.id.goog[&lt;NAMESPACE>/csp-health-monitor]"

Helm Configuration

1 csp-health-monitor:
2   cspName: "gcp"
3   configToml:
4     clusterName: "my-gke-cluster"
5     gcp:
6       targetProjectId: "&lt;TARGET_PROJECT_ID>"
7       gcpServiceAccountName: "&lt;GCP_SA_NAME>"
8       apiPollingIntervalSeconds: 60
9       logFilter: 'logName="projects/&lt;TARGET_PROJECT_ID>/logs/cloudaudit.googleapis.com%2Fsystem_event" AND protoPayload.methodName="compute.instances.upcomingMaintenance"'

Amazon Web Services (AWS)

Required IAM Permissions

health:DescribeEvents - Query AWS Health API for maintenance events
health:DescribeAffectedEntities - Get affected EC2 instance IDs
health:DescribeEventDetails - Get event details and recommended actions

Setup Commands

Replace placeholders:

<CLUSTER_NAME> - EKS cluster name
<NAMESPACE> - Kubernetes namespace (default: nvsentinel)

$ # 1. Create IAM policy
$ aws iam create-policy \
>     --policy-name CSPHealthMonitorPolicy \
>     --policy-document '\{
>         "Version": "2012-10-17",
>         "Statement": [
>             \{
>                 "Effect": "Allow",
>                 "Action": [
>                     "health:DescribeEvents",
>                     "health:DescribeAffectedEntities",
>                     "health:DescribeEventDetails"
>                 ],
>                 "Resource": "*"
>             \}
>         ]
>     \}'
$ 
$ # 2. Get OIDC provider and Account ID
$ OIDC_PROVIDER=$(aws eks describe-cluster --name &lt;CLUSTER_NAME> --query "cluster.identity.oidc.issuer" --output text | sed 's|https://||')
$ ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
$ 
$ # 3. Create trust policy file
$ cat > trust-policy.json &lt;&lt; EOF
$ \{
$     "Version": "2012-10-17",
$     "Statement": [
>         \{
>             "Effect": "Allow",
>             "Principal": \{
>                 "Federated": "arn:aws:iam::$\{ACCOUNT_ID\}:oidc-provider/$\{OIDC_PROVIDER\}"
>             \},
>             "Action": "sts:AssumeRoleWithWebIdentity",
>             "Condition": \{
>                 "StringEquals": \{
>                     "$\{OIDC_PROVIDER\}:aud": "sts.amazonaws.com",
>                     "$\{OIDC_PROVIDER\}:sub": "system:serviceaccount:&lt;NAMESPACE>:csp-health-monitor"
>                 \}
>             \}
>         \}
>     ]
$ \}
$ EOF
$ 
$ # 4. Create IAM role
$ aws iam create-role \
>     --role-name &lt;CLUSTER_NAME>-nvsentinel-health-monitor-assume-role-policy \
>     --assume-role-policy-document file://trust-policy.json
$ 
$ # 5. Attach policy to role
$ aws iam attach-role-policy \
>     --role-name &lt;CLUSTER_NAME>-nvsentinel-health-monitor-assume-role-policy \
>     --policy-arn arn:aws:iam::$\{ACCOUNT_ID\}:policy/CSPHealthMonitorPolicy

Helm Configuration

1 csp-health-monitor:
2   cspName: "aws"
3   configToml:
4     clusterName: "&lt;CLUSTER_NAME>"
5     aws:
6       accountId: "&lt;ACCOUNT_ID>"
7       region: "&lt;AWS_REGION>"
8       pollingIntervalSeconds: 60
9       # Optional: override the default IAM role name
10       # iamRoleName: "my-custom-nvsentinel-role"

Important (EKS): By default, the IAM role name is constructed as <CLUSTER_NAME>-nvsentinel-health-monitor-assume-role-policy. AWS IAM role names have a 64-character limit, and the default suffix is 45 characters, leaving only 19 characters for the cluster name. If your cluster name exceeds 19 characters, set aws.iamRoleName to a custom role name and create the IAM role with that name instead:
$ aws iam create-role \
>     --role-name my-custom-nvsentinel-role \
>     --assume-role-policy-document file://trust-policy.json
Then in Helm values:
1 aws:
2   iamRoleName: "my-custom-nvsentinel-role"

Additional Resources

Configuration Guide: See docs/configuration/csp-health-monitor.md for detailed Helm configuration options
Troubleshooting: See docs/runbooks/csp-health-monitor-iam.md for common issues and solutions

$	# 1. Create GCP Service Account
$	gcloud iam service-accounts create <GCP_SA_NAME> \
>	--display-name="CSP Health Monitor Service Account" \
>	--project=<TARGET_PROJECT_ID>
$
$	# 2. Create custom IAM role with minimal permissions
$	gcloud iam roles create cspHealthMonitorRole \
>	--project=<TARGET_PROJECT_ID> \
>	--title="CSP Health Monitor Role" \
>	--description="Minimal permissions for CSP Health Monitor" \
>	--permissions="logging.logEntries.list"
$
$	# 3. Grant role to GCP Service Account
$	gcloud projects add-iam-policy-binding <TARGET_PROJECT_ID> \
>	--member="serviceAccount:<GCP_SA_NAME>@<TARGET_PROJECT_ID>.iam.gserviceaccount.com" \
>	--role="projects/<TARGET_PROJECT_ID>/roles/cspHealthMonitorRole"
$
$	# 4. Enable Workload Identity binding
$	gcloud iam service-accounts add-iam-policy-binding \
>	<GCP_SA_NAME>@<TARGET_PROJECT_ID>.iam.gserviceaccount.com \
>	--role="roles/iam.workloadIdentityUser" \
>	--member="serviceAccount:<GKE_PROJECT_ID>.svc.id.goog[<NAMESPACE>/csp-health-monitor]"

1	csp-health-monitor:
2	cspName: "gcp"
3	configToml:
4	clusterName: "my-gke-cluster"
5	gcp:
6	targetProjectId: "<TARGET_PROJECT_ID>"
7	gcpServiceAccountName: "<GCP_SA_NAME>"
8	apiPollingIntervalSeconds: 60
9	logFilter: 'logName="projects/<TARGET_PROJECT_ID>/logs/cloudaudit.googleapis.com%2Fsystem_event" AND protoPayload.methodName="compute.instances.upcomingMaintenance"'

$	# 1. Create IAM policy
$	aws iam create-policy \
>	--policy-name CSPHealthMonitorPolicy \
>	--policy-document '\{
>	"Version": "2012-10-17",
>	"Statement": [
>	\{
>	"Effect": "Allow",
>	"Action": [
>	"health:DescribeEvents",
>	"health:DescribeAffectedEntities",
>	"health:DescribeEventDetails"
>	],
>	"Resource": "*"
>	\}
>	]
>	\}'
$
$	# 2. Get OIDC provider and Account ID
$	OIDC_PROVIDER=$(aws eks describe-cluster --name <CLUSTER_NAME> --query "cluster.identity.oidc.issuer" --output text \| sed 's\|https://\|\|')
$	ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
$
$	# 3. Create trust policy file
$	cat > trust-policy.json << EOF
$	\{
$	"Version": "2012-10-17",
$	"Statement": [
>	\{
>	"Effect": "Allow",
>	"Principal": \{
>	"Federated": "arn:aws:iam::$\{ACCOUNT_ID\}:oidc-provider/$\{OIDC_PROVIDER\}"
>	\},
>	"Action": "sts:AssumeRoleWithWebIdentity",
>	"Condition": \{
>	"StringEquals": \{
>	"$\{OIDC_PROVIDER\}:aud": "sts.amazonaws.com",
>	"$\{OIDC_PROVIDER\}:sub": "system:serviceaccount:<NAMESPACE>:csp-health-monitor"
>	\}
>	\}
>	\}
>	]
$	\}
$	EOF
$
$	# 4. Create IAM role
$	aws iam create-role \
>	--role-name <CLUSTER_NAME>-nvsentinel-health-monitor-assume-role-policy \
>	--assume-role-policy-document file://trust-policy.json
$
$	# 5. Attach policy to role
$	aws iam attach-role-policy \
>	--role-name <CLUSTER_NAME>-nvsentinel-health-monitor-assume-role-policy \
>	--policy-arn arn:aws:iam::$\{ACCOUNT_ID\}:policy/CSPHealthMonitorPolicy

1	csp-health-monitor:
2	cspName: "aws"
3	configToml:
4	clusterName: "<CLUSTER_NAME>"
5	aws:
6	accountId: "<ACCOUNT_ID>"
7	region: "<AWS_REGION>"
8	pollingIntervalSeconds: 60
9	# Optional: override the default IAM role name
10	# iamRoleName: "my-custom-nvsentinel-role"

$	aws iam create-role \
>	--role-name my-custom-nvsentinel-role \
>	--assume-role-policy-document file://trust-policy.json