Linking Your AWS Account to SUSE Rancher for AWS

Before creating EKS clusters in SUSE Rancher for AWS (SRFA), you must link your AWS account by creating a cloud credential.

Why Link AWS Accounts

SUSE Rancher for AWS uses AWS IAM roles to securely access your AWS account for cluster management. Benefits include:

No Static Credentials

SUSE Rancher for AWS does not store AWS access keys.

IAM Role-Based

Uses AWS’s secure role assumption mechanism.

Temporary Credentials

Short-lived credentials automatically refresh.

Audit Trail

All API calls are logged in AWS CloudTrail.

Multi-Account Support

Link multiple AWS accounts from a single interface.

Required Permissions

SUSE Rancher for AWS’s IAM role needs permissions for:

  • EKS cluster management

  • EC2 instances, VPCs, subnets, and security groups

  • Load balancers for services

  • IAM role management for Pod Identity

  • CloudFormation stack reading

Use SUSE Rancher for AWS’s CloudFormation template to ensure correct permissions. The full IAM policy is available in the provided srfa-iam-roles.yaml template.

Method 1: CloudFormation Quick Deploy (Recommended)

This method is recommended for first-time setup and for users with AWS CloudFormation permissions. It uses an automated template to correctly configure the required trust policies and IAM permissions.

For detailed instructions on using this method, refer to Step 2: Link AWS Account in the Quick Start guide.

Method 2: Existing Role ARN

This method is recommended if you have pre-created roles, are setting up secondary credentials, or use centralized IAM management.

  1. Navigate to the Link AWS Account card on the SUSE Rancher for AWS home page, or go to Cluster Manager > Accounts > Create.

  2. Enter a Name and select your Default Region.

  3. Select I have an existing role ARN.

  4. Enter the Role ARN using the format arn:aws:iam::<account-id>:role/<role-name> (for example, arn:aws:iam::123456789012:role/SRFAManagementRole).

  5. Click Create.

ARN Validation Requirements

  • Must start with arn:aws:iam::.

  • Must contain :role/ (not :user/).

  • Cannot include region identifiers, as IAM ARNs are globally scoped.

Method 3: Download Template

This method is suitable for users without CloudFormation permissions who must request an administrator to provision resources.

  1. Navigate to the Link AWS Account card.

  2. Select I need to set up a new role.

  3. Click Download Template.

  4. Share the template (srfa-iam-roles.yaml) with your AWS administrator.

  5. The administrator deploys the stack. For example, using the AWS CLI:

    aws cloudformation create-stack \
  --stack-name SRFA-IAM-Role \
  --template-body file://srfa-iam-roles.yaml \
  --parameters ParameterKey=tenantAccount,ParameterValue=<tenant-uid> \
               ParameterKey=tenantName,ParameterValue=<your-org> \
  --capabilities CAPABILITY_NAMED_IAM

  6. Obtain the successfully generated Role ARN from the administrator.

  7. Follow the steps in Method 2: Existing Role ARN to register the credential.

Verification

SUSE Rancher for AWS automatically validates the configuration upon creation:

  • Verifies the role exists in AWS.

  • Verifies the trust relationship allows role assumption.

  • Confirms regional connectivity.

  • Validates base permissions.

A successful link triggers a success banner, and the credential appears with an Active status on the Accounts page.

Common Issues

"Role cannot be assumed"

Cause

The trust policy is missing or incorrectly configured.

Fix

Edit the role’s trust policy in the IAM console and add the required SUSE Rancher for AWS principal ARN.

Permission Denied

Cause

Missing essential EKS, EC2, or IAM permissions.

Fix

Re-deploy using SUSE Rancher for AWS’s CloudFormation template or attach the missing policies manually.

Invalid ARN Format

Cause

The provided ARN does not strictly match an IAM Role ARN structure.

Fix

Use the format arn:aws:iam::<account-id>:role/<role-name>.

CloudFormation Stack Failed

Cause

Missing account-level IAM creation permissions, or the user forgot to check the capability acknowledgment box.

Fix

Delete the failed stack and retry the operation with the correct acknowledgments or elevated privileges.

Managing Credentials

Viewing

Navigate to Cluster Manager > Accounts to view a list of all cloud credentials. This interface displays the name, description, default region, account ID, creation date, and status (Active or Error).

Editing

  1. Click the credential name or Edit icon.

  2. Modify the permitted fields (Name, Description, Default Region, or Role ARN if the role was entirely recreated).

  3. Click Save.

You cannot change the ARN for a credential currently in use by active clusters.

Deleting

Deleting a credential within SUSE Rancher for AWS does not delete the IAM role or any underlying AWS resources. However, active clusters provisioned with that credential will remain in AWS but cannot be managed via SUSE Rancher for AWS until the credential is recreated and linked again.

  1. Ensure no clusters are actively using the credential.

  2. Click the Actions menu (⋮) and select Delete.

  3. Confirm the deletion.

Multi-Account Strategy

When to Use Multiple Credentials

  • To enforce separation between production and development environments.

  • Across different AWS organizations for distinct business units.

  • Applying different IAM roles with varying levels of permission scoping.

  • For precise cost allocation and billing separation.

Naming Conventions

Implement descriptive names that indicate the environment, account purpose, and primary region.

For example: * aws-prod-platform * aws-dev-engineering * aws-staging-qa

Credential Selection

When provisioning a cluster, SUSE Rancher for AWS prompts you to select a cloud credential from a dropdown. The Default Region assigned to that credential will automatically pre-select the targeted provisioning region.

Security Best Practices

IAM Role Configuration

  • Adhere to the principle of least privilege by granting only explicitly required permissions.

  • Enable CloudTrail to continuously audit API calls made via the SUSE Rancher for AWS integration.

  • Apply resource-based condition keys to constrain actions to authorized regions.

  • Utilize the IAM Access Analyzer to actively validate configured trust policies.

  • Perform regular reviews and enforce IAM role rotation policies.

Credential Management in SUSE Rancher for AWS

  • Restrict credential creation and editing privileges strictly to administrators or designated cluster creators.

  • Use clear descriptions and naming conventions to document the distinct purpose of each credential.

  • Conduct periodic audits to remove deprecated or unused credentials.

  • Monitor integration alerts for "Permission Denied" errors that may indicate unauthorized access attempts or drifting permission scopes.

Trust Policy Example

The underlying SUSE Rancher for AWS IAM role trust policy should be configured as follows:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::<srfa-account-id>:role/<srfa-role-name>"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "<tenant-uid>"
      }
    }
  }]
}

Troubleshooting Credential Issues

Credential Shows "Error" Status

Verify that the IAM role still exists in the AWS Console, the trust policy matches the SUSE Rancher for AWS requirements and has not been altered, and the target AWS account has no standing issues (such as reached billing limits). Check for regional API network connectivity.

To resolve, re-verify the role ARN format and re-save the credential within SUSE Rancher for AWS to trigger forced re-validation.

Cannot Create Clusters with Credential

If validation fails when attempting to create a cluster, ensure the role has the following critical permissions: * eks:CreateCluster, eks:DescribeCluster * ec2:CreateVpc, ec2:CreateSubnet * iam:CreateRole, iam:AttachRolePolicy

Review the CloudFormation template to verify parity with the role’s attached policies. Use the AWS Policy Simulator to safely test permissions and append any missing configurations.

Credential Works But Cluster Creation Fails

Common causes for failure post-credential validation include reaching AWS service limits (such as the cap for EKS clusters per region or concurrent EC2 instances), specifying a region that lacks support for EKS or the configured instance types, or exhausting available IPs within the configured VPC and subnets.