Configuring a service connection to Yandex Cloud in SourceCraft

Service connections allow you to securely integrate your SourceCraft projects with the Yandex Cloud resources.

With service connections, you can get access to the Yandex Cloud API from inside of your SourceCraft repository's CI/CD workflows. For example, you can request a secret from Yandex Lockbox, upload files to a Yandex Object Storage bucket, deploy a virtual machine in Yandex Compute Cloud, etc.

You do not have to keep any long-lived tokens or access keys in repository secrets, let alone your code. You get authenticated in Yandex Cloud via a short-lived Yandex Identity and Access Management IAM token which is requested within each individual CI/CD task.

Learn more about service connections.

This guide will use the example of getting a list of Yandex Cloud Functions functions.

To configure a service connection:

Create a Yandex Cloud service account

A service account is an account that can be used by a program to manage resources in Yandex Cloud.

To create a service account:

In the Yandex Cloud management console, select the folder containing resources you want to configure access to from SourceCraft.
Navigate to Identity and Access Management.
Click Create service account.
Enter a name for the service account.

The naming requirements are as follows:
- Length: between 3 and 63 characters.
- It can only contain lowercase Latin letters, numbers, and hyphens.
- It must start with a letter and cannot end with a hyphen.
Make sure the service account name is unique within your cloud.
Click Create.

For more information, see Creating a service account.

Assign a role to the service account

A role is a set of permissions that defines the allowed scope of operations with Yandex Cloud resources.

To assign a role for a folder to a service account:

In the Yandex Cloud management console, select the folder with the service account you created earlier.
Navigate to the Access bindings tab.
Click Configure access.
In the window that opens, select Service accounts.
Select the service account from the list or use the search bar.
Click Add role and select the role from the list or use the search bar.

For example, assign the functions.viewer role to the service account to enable it to view Cloud Functions functions.
Click Save.

Learn more about assigning roles to a service account.

Create a service connection

You can create two types of service connections:

Organization-level: Available from all organization repositories if the scope is not restricted. To create such a connection, you need the Organization admin role.
Repository-level: Only available from a specific repository. To create such a connection, you need the Repository admin role. This role grants permissions to create and modify connections for this specific repository and provides read-only access to the list of connections available to all the organization’s repositories.

At the organizational level

At the repository level

Open the SourceCraft home page.
Navigate to the Organizations tab.
Select the organization.
On the organization page, in the Settings section, go to the Service connections section.
Click New service connection.
In the window that opens:
- Under Basic information, give the connection a name, e.g., default-service-connection, and add an optional description.
- Under Scope, select the repositories and branches the service connection will be available to.
- Under Yandex Cloud settings, select:
  - Folder containing the resources you want to configure access to from SourceCraft.
  - Service account you created earlier.
  Tip
  
  To re-request the list of clouds, folders, and service accounts from Yandex Cloud, click Synchronize. This can be of use if alongside creating a service connection you also created a folder or service account.
Click Create service connection.

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories.
Select a repository.
Under Repository settings on the repository page, go to Service connections.
Click New service connection.
In the window that opens:
- Under Basic information, give the connection a name, e.g., default-service-connection, and add an optional description.
- Under Scope, select the branches the service connection will be available to.
- Under Yandex Cloud settings, select:
  - Folder containing the resources you want to configure access to from SourceCraft.
  - Service account you created earlier.
  Tip
  
  To re-request the list of clouds, folders, and service accounts from Yandex Cloud, click Synchronize. This can be of use if alongside creating a service connection you also created a folder or service account.
Click Create service connection.

Wait for the operation to complete. The page that opens will display the service connection details.

A Yandex Identity and Access Management workload identity federation will be automatically created in Yandex Cloud.

To view the parameters of the new OIDC provider, click the federation name under Workload identity federation.

Prepare the CI/CD configuration

Tip

You can set up and view repository configurations in the SourceCraft interface under Repository settings in the Configurations section. For more information, see Setting up repository configurations as code.

Configure CI/CD in your repository.
Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.
Under Code on the repository page, go to Branches.
Select the branch for editing.
Open the .sourcecraft/ci.yaml file.
In the top-right corner, click Edit.

Add the tokens and env sections you got earlier into the CI/CD configuration.

You can get an IAM token via a ready-made cube from the SourceCraft team. Below is an example of a CI/CD configuration where the IAM token is used for authentication in the Yandex Cloud CLI to get a list of Cloud Functions functions.

tokens:
  # Token name (can be any).
  <token_name>:
    # Name of the service connection you created earlier.
    service_connection: <service_connection_name>
    # Requested access scope:
    # org: All repositories
    # repo: Specific repository
    # ref: Branch or tag
    scope: repo

workflows:
  test-workflow:
    tasks:
      - name: sample-task
        cubes:
          # The cube exchanges the SourceCraft token for the Yandex Cloud IAM token
          # and saves it to the `IAM_TOKEN` variable within the `outputs` section.
          - name: get-iam-token
            env:
              ID_TOKEN: ${{ tokens.<token_name>.id_token }}
              YC_SA_ID: ${{ tokens.<token_name>.service_account_id }}
              # You can also get the folder and cloud IDs
              # YC_FOLDER_ID: ${{ tokens.<token_name>.folder_id }}
              # YC_CLOUD_ID: ${{ tokens.<token_name>.cloud_id }}
            image: cr.yandex/sourcecraft/yc-iam:latest

          # The cube with pre-installed Yandex Cloud CLI retrieves 
          # the IAM_TOKEN from `outputs` and uses it to get the list of Cloud Functions functions.
          - name: get-functions
            env:
              # Substitute to the `outputs` section the name of the IAM token cube,
              # e.g., `get-iam-token`.
              YC_IAM_TOKEN: ${{ cubes.<IAM_token_cube_name>.outputs.IAM_TOKEN }}
              YC_FOLDER_ID: ${{ tokens.<token_name>.folder_id }}
            image: 
              name: cr.yandex/sourcecraft/yc-cli:latest
              entrypoint: ""
            script:
              - |
                yc config set folder-id $YC_FOLDER_ID
                yc serverless function list

on:
  push: test-workflow

Tip

You can interact with Yandex Cloud directly via the API or use one of the following:

Yandex Cloud CLI: For authentication, provide the IAM token to the YC_IAM_TOKEN environment variable, and use the --cloud-id and --folder-id parameters for cloud and folder IDs in the commands.
Terraform: For authentication, provide the IAM token to the YC_TOKEN environment variable; provide cloud and folder IDs to the YC_CLOUD_ID and YC_FOLDER_ID environment variables.
SDK: Authentication is similar to the API.

In the top-right corner, click Commit changes.
In the window that opens, configure the procedure for changes:
- In the Commit message field, give a comment that will describe the changes you make.
- Under Commit branch, select the branch you want to change. Create a new branch as needed.
- Under After commit action, select how to make changes: via a commit or a pull request.
Confirm your changes.

If you opted for a pull request, finish creating it.

Test the service connection

Under Code on the repository page, go to CI/CD.
Select a running workflow.
The page that opens will display the workflow tasks, cubes (task steps), as well as statuses and execution results.

In the bottom-right corner of the get-functions cube, click .

Here is an example of the get-functions cube logs:

+----------------------+--------+----------------------+--------+
|          ID          |  NAME  |      FOLDER ID       | STATUS |
+----------------------+--------+----------------------+--------+
| d4e5l4qjepst******** | test-1 | b1gveg9vude9******** | ACTIVE |
+----------------------+--------+----------------------+--------+

Tip

An IAM token is valid for 12 hours. However, we recommend terminating it after use for security purposes. For more information, see Revoking an IAM token.

Was the article helpful?

Setting up a self-hosted worker

Using GitHub Actions