Fractal Cloud Environment Initialization

Initialize a Fractal Cloud Environment

You can initialize a Fractal Cloud Environment either through our Web UI or through our SDK

Use the Web UI

To initialize the Fractal Cloud Agent using the user interface follow the steps below:

1. Choose the Environment

Ensure you have an environment where you want to initialize the Fractal Cloud Agent. If you do not, follow the Quick Start guide.

2. Open the Configuration Panel Navigate to the configuration panel by selecting the Configure button on the Environments dashboard.

3. Navigate to Cloud Agents tab

Within the configuration panel, find and select the Cloud Agents tab. This will take you to a section where you can initialize Fractal Cloud agents.

4. Select a Cloud Provider

A list of cloud providers will be displayed, including Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP), and Oracle Cloud Infrastructure (OCI). As of now, only Microsoft Azure is available for evaluation purposes via the Web UI.

Availability

Currently, Microsoft Azure is the only cloud provider available for evaluation purposes. To use the Fractal Cloud, users must have at least one active subscription with Azure. This subscription is necessary for the creation of cloud resources needed by the Fractal Cloud Agent. Please ensure you have an active subscription with billing enabled before initiating the setup process, and that your user has the correct access to the subscription.

Integration with Amazon Web Services (AWS), Google Cloud Platform (GCP), and Oracle Cloud Infrastructure (OCI) is currently available for enterprise customers only.

Select the Cloud Provider to initialize to proceed.

5. Initialize the Fractal Cloud Agent

Once the cloud provider is selected, click on the Initialize button to start the initialization process for the Fractal Cloud Agent. Cloud Agents are essential components of Fractal Cloud's automated infrastructure deployment, deployed within your Cloud Infrastructure Landscape. To disconnect your environment from Fractal Cloud, you can use the UI or SDK to remove the Environment, this will also remove all Fractal Cloud Agent resources within your Cloud Infrastructure Landscape.

NOTE

Do not manually modify or delete any Fractal Cloud Agent resources.

6. Follow On-Screen Instructions

The UI will guide you through the necessary steps to complete the initialization. This may include authenticating with your cloud provider, selecting specific resources, or configuring settings specific to your environment.

Understanding OAuth 2.0 Azure Device Flow

During the initialization of the Cloud Agent on your Azure subscription, we use OAuth 2.0 Device Flow for authentication. This secure authentication method allows users to grant applications access to their cloud account without directly sharing login credentials.

Here's how it works:

You will be provided with a device code.
You'll be asked to visit a specific URL on a web browser.
Once there, you will enter the provided device code to authenticate the application.
After successful authentication, the Fractal Cloud setup will proceed, creating necessary resources on your behalf.

This process ensures that the Fractal Cloud Agent has the permissions it needs to operate within your cloud environment securely and efficiently. In order to initialize the Azure Subscription correctly, ensure you have assigned the roles Contributor and Role Based Access Control Administrator on the subscription selected.

Use the SDK

Availability

SDK-based environment initialization is currently available for enterprise customers only.

Use the SDK to initialize the Fractal Cloud Agent programmatically, typically as part of a CI/CD pipeline. Supported cloud providers are:

Microsoft Azure
Google Cloud Platform (GCP)

1. Create a Fractal Resource Group

Ensure you have a Fractal Resource Group you can use for your new Environments. If you do not, follow the Quick Start guide to create one.

2. Initialize for Your Cloud Provider The SDK automatically creates the Cloud Agent and related resources during initialization.

Microsoft Azure Initialization

The SDK checks if the environment exists in Fractal Cloud.
If not, it creates the environment and all required Cloud Agent resources.

Your program must impersonate an Azure Service Principal with the following permissions:

# Create a new service principal if needed (usually done only once)
az ad sp create-for-rbac --name "Fractal Cloud Initializer"

# Grant the "Contributor" and "Role Based Access Control Administrator" roles on each Azure subscription where the Fractal Cloud Agent requires access
az role assignment create --assignee <SERVICE_PRINCIPAL_ID> --role "Contributor" --scope /subscriptions/<SUBSCRIPTION_ID>
az role assignment create --assignee <SERVICE_PRINCIPAL_ID> --role "Role Based Access Control Administrator" --scope /subscriptions/<SUBSCRIPTION_ID>

# Enable the Fractal Cloud Agent to assign MS Graph roles
az ad app permission add --id <SERVICE_PRINCIPAL_ID> --api 00000003-0000-0000-c000-000000000000 --api-permissions 9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30=Role
az ad app permission grant --id <SERVICE_PRINCIPAL_ID> --api 00000003-0000-0000-c000-000000000000 --scope 9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30

az ad app permission add --id <SERVICE_PRINCIPAL_ID> --api 00000003-0000-0000-c000-000000000000 --api-permissions 06b708a9-e830-4db3-a914-8e69da51d44f=Role
az ad app permission grant --id <SERVICE_PRINCIPAL_ID> --api 00000003-0000-0000-c000-000000000000 --scope 06b708a9-e830-4db3-a914-8e69da51d44f

In order to ensure all is good, ensure you have the expected roles and permissions assigned to the service principal using the following commands:

az ad app permission list --id <SERVICE_PRINCIPAL_ID>
# It should output something like the following:
#[
#  {
#    ...
#    "roleDefinitionName": "Contributor",
#    "scope": "/subscriptions/<SUBSCRIPTION_ID>",
#    ...
#  },
#  {
#    ...
#    "roleDefinitionName": "Role Based Access Control Administrator",
#    "scope": "/subscriptions/6c70be66-eee1-4ef3-a2cd-0878d504653f",
#    ...
#  }
#]

az role assignment list --assignee <SERVICE_PRINCIPAL_ID>
# It should output something like the following:
#[
#  {
#    "resourceAccess": [
#      {
#        "id": "06b708a9-e830-4db3-a914-8e69da51d44f",
#        "type": "Role"
#      },
#      {
#        "id": "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30",
#        "type": "Role"
#      }
#    ],
#    "resourceAppId": "00000003-0000-0000-c000-000000000000"
#  }
#]

Google Cloud Platform (GCP) Initialization

The SDK performs the following steps when initializing a GCP environment:

Checks if the environment exists in Fractal Cloud.
Creates the environment and required Cloud Agent resources if it does not exist.

Note:

GCP initialization is currently available only via the SDK (no Web UI support yet).

Required Environment Variables:

Set these environment variables to allow the SDK to authenticate with your GCP service account:

Variable	Description
`GCP_SERVICE_ACCOUNT_EMAIL`	Email of the GCP service account
`GCP_SERVICE_ACCOUNT_CREDENTIALS`	Service account key JSON (can be raw JSON or base64-encoded)

Create the GCP Service Account

Use the following commands to create the service account and assign the necessary roles:

# Create the service account
gcloud iam service-accounts create fractal-cloud-initializer \
  --display-name "Fractal Cloud Initializer"

# Assign required roles to the service account
PROJECT_ID="your-project-id"
SERVICE_ACCOUNT="fractal-cloud-initializer@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/editor

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/compute.networkAdmin

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/serviceusage.serviceUsageAdmin

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/resourcemanager.projectIamAdmin

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/secretmanager.admin

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:$SERVICE_ACCOUNT" \
  --role roles/run.admin

Important

Make sure the Service Usage API is enabled for your project. The initialization process will automatically enable additional required APIs.

gcloud services enable serviceusage.googleapis.com

3. Initialize the Environment programmatically

Cloud Agents are essential components of Fractal Cloud's automated infrastructure deployment, deployed within your Cloud Infrastructure Landscape. To disconnect your environment from Fractal Cloud, you can use the UI or SDK to remove the Environment, this will also remove all Fractal Cloud Agent resources within your Cloud Infrastructure Landscape.

NOTE

Do not manually modify any resources within the rg-fractal Resource Group.

Follow the sample on how to use our SDK to initialize your new Environment.

NOTE

Ensure that Admin Consent is granted for MS Graph roles after assigning them by following this guide.

Initialize a Fractal Cloud Environment​

Use the Web UI​

Use the SDK​

Microsoft Azure Initialization​

Google Cloud Platform (GCP) Initialization​

Required Environment Variables:​

Create the GCP Service Account​

Initialize a Fractal Cloud Environment

Use the Web UI

Use the SDK

Microsoft Azure Initialization

Google Cloud Platform (GCP) Initialization

Required Environment Variables:

Create the GCP Service Account