Service Roles

Service Roles

Service Roles

Introduction

You will need to configure a service role within a Citadel environment. These step-by-step instructions demonstrate how to use GitHub, GitLab, and BitBucket.

What is a Service Role?

A service role is an IAM Role that trusts a provider via OIDC.

The supported providers are: GitHub, GitLab, and BitBucket.

The service role is used to allow external providers to perform changes in your AWS infrastructure. Some common use cases are:

  • Deploying Applications
  • Deploying Infrastructure with tools like AWS CLI (CloudFormation), Terraform, etc.
  • Copying files to an S3 bucket for a static website

Creating a service role

Let's now configure the service role through which your AWS Account communicates with a vendor (GitHub, GitLab, BitBucket).

  1. Sign in to Citadel and navigate to the Environment section
  2. If you do not have an Environment created, click on Create an environment
  3. Follow the instructions at
    Environments
    Environments
  4. On the Environment page, on the left side, select the Service Roles menu
  5. To create a new service role, click the New Service Role button
  6. Fill out the fields as directed below:
    1. Enter the Role Name that will be able to deploy AWS resources using the selected provider
    2. Select the Provider of your CI supports OIDC or Custom for user-based authentication
    3. Select Policy Sets to configure the role's permissions (see more below)
    4. Enter the Organization Name (or team name when using Bitbucket)
    5. Enter the Workspace UUID (only when using Bitbucket). To find this value, see below
    6. Click Create
image

Finding the Workspace UUID (Bitbucket only)

To find your Workspace UUID:

  1. Navigate to any repository in your Bitbucket team
  2. Click Repository Settings
  3. Click OpenID Connect
  4. Copy the Workspace UUID as shown in the screenshot below
image

Policy Sets

Policy Sets are IAM policies fine-tuned for a specific purpose.

Currently, Citadel ships with 3 policy sets:

Administrator

Allows any action in the AWS accounts.

This policy set should be avoided as it breaks the principle of least-privilege.

When use is required, make sure that the provider using this role has proper security controls in place to avoid unauthorized actions.

Serverless

This role is intended for the deployment of serverless apps. It includes apps deployed with the frameworks:

ECS / ECR

This role is suited for pushing Docker images to ECR and deploying ECS services.

⚠️
These policies are built and tested regularly by the Citadel team. Due to changes to the frameworks and new AWS services, policies might need to be updated. Please contact support if you believe a policy set is missing permissions to perform necessary actions.

Custom Policies (coming soon)

Allows a user to add custom policies to the role.

Configure BitBucket Pipeline

Configure a BitBucket pipeline to build and deploy changes to your project. A basic configuration can do things like write scripts to create a cluster, configure and manage different resources.

pipelines:

pull-requests:
	'**': #this runs as default for any branch not elsewhere defined
		- step:
			script:
				- ...
			feature/citadel-*: #any branch with a “feature/citadel-” prefix
		- step:
			script:
				- ...
	
		branches: #these will run on every push of the branch
		staging:
			- step:
			script:
				- ...
Pipeline sample.

Credentials

You need to set up a credential configuration to allow any deployment in the AWS Account.

Create 2 variables to the repository.

  1. Navigate to BitBucket > Repository variables
    1. Go to your BitBucket Repository;
    2. Select Repository setting on left menu;
    3. Select Repository variables on the left menu;
  2. Create 2 variables:
    1. Variable 1:

      2. Name: AWS_REGION

      Value: Region of the environment

    2. Variable 2:

      3. Name: AWS_ROLE_ARN

      Value: arn:aws:iam::<account_number>:role/<role_name>**

      Role_name: Role name assigned to the service role.

Image shows the 2 variables created on BitBucket.
Image shows the 2 variables created on BitBucket.

Enable the service role for pipeline steps:

Add the OIDC to the the pipeline workspace file in the steps section that you need to run:

Example:

oidc: true

As per the documentation here, you simply need to add the AWS_WEB_IDENTITY_TOKEN_FILE environment variable.

– export AWS_WEB_IDENTITY_TOKEN_FILE=$(pwd)/web-identity-token

– echo $BITBUCKET_STEP_OIDC_TOKEN > $(pwd)/web-identity-token

The example below shows a how the pipeline would look like.

image

Configure GitLab Pipeline

Configure a GitLab pipeline to build and deploy changes to your project. A basic configuration can do things like write scripts to create a cluster, configure and manage different resources.

  1. Set up GitLab repository: The first step is to create (if it doesn’t exist) a GitLab repository that will host your project.
  2. Create a blueprint: You can create a blueprint in GitLab by adding a file in the root directory of your repository with the .gitlab-ci.yml extension. This file will contain the definition of your pipeline, including the steps and actions that will be performed.
  3. AWS credentials: In order to run your pipeline to AWS, you need to set up AWS credentials in GitLab.

Credentials

You can set up aws-actions/configure-aws-credentials@v1 to run the pipeline with an AWS Role with permission to deploy the resources you are running.


name: GitLab Pipeline

on:
  workflow_dispatch:
    inputs:

  push:
    

jobs:
  name: Get Workspaces
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read

  steps:
    - name: configure aws credentials
      uses: aws-actions/configure-aws-credentials@v1
      with:
				role-to-assume: arn:aws:iam::000000000000:role/CIDeployGitLab
        role-session-name: github-deploy
        aws-region: ap-southeast-2 # set your region
Example (a). GitLab pipeline using configure-aws-credentials.

This can be done by creating a new environment variable in your GitLab repository with your AWS access key and secret access key.

name: GitLab Pipeline

on:
  workflow_dispatch:
    inputs:

  push:
    

jobs:
  name: Get Workspaces
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read

  steps:
    - name: configure aws credentials
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ secrets.AWS_REGION }}
Example (b). GitLab pipeline using gitlab keys.

In this example, the AWS configure command sets the AWS credentials using the environment variables $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY.

For more information on how to set up a blueprint in GitLab and run pipelines to AWS, you can refer to the official GitLab documentation:

Configure GitHub Pipeline

Configure a GitHub pipeline to build and deploy changes to your project. A basic configuration can do things like write scripts to create a cluster, configure and manage different resources.

  1. Set up GitHub repository: The first step is to create (if it doesn’t exist) a GitHub repository that will host your project.
  2. Create a blueprint: You can create a blueprint in GitHub by adding a file in the root directory of your repository with the .workflows/github/file-name.yml extension. This file will contain the definition of your pipeline, including the steps and actions that will be performed.
  3. AWS credentials: In order to run your pipeline to AWS, you need to set up AWS credentials in GitHub.

Credentials

You can set up aws-actions/configure-aws-credentials@v1 to run the pipeline with an AWS Role with permission to deploy the resources you are running.


name: GitHub Pipeline

on:
  workflow_dispatch:
    inputs:

  push:
    

jobs:
  name: Get Workspaces
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read

  steps:
    - name: configure aws credentials
      uses: aws-actions/configure-aws-credentials@v1
      with:
				role-to-assume: arn:aws:iam::000000000000:role/CIDeployGitHub
        role-session-name: github-deploy
        aws-region: ap-southeast-2 # set your region
Example (a). GitLab pipeline using configure-aws-credentials.

This can be done by creating a new environment variable in your GitHub repository with your AWS access key and secret access key.

name: GitHub Pipeline

on:
  workflow_dispatch:
    inputs:

  push:
    

jobs:
  name: Get Workspaces
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read

  steps:
    - name: configure aws credentials
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ secrets.AWS_REGION }}
Example (b). GitLab pipeline using gitlab keys.

In this example, the AWS configure command sets the AWS credentials using the environment variables $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY.

Redeploy a Service Role

  1. Go to Citadel.Run;
  2. Select Environments on the Menu;
  3. Select the Environment you want to redeploy;
  4. Select Service Roles on the left menu;
  5. Find the service role you want to redeploy and click on the three dots on the right side;
  6. Click Redeploy.

image

For more information on how to set up a blueprint in GitLab and run pipelines to AWS, you can refer to the official GitHub documentation:

← Previous

Environments
Environments

Next →

Domains
Domains