Fractal Cloud Environment Initialization
Why do you need to initialize an environment?
Environment initialization in Fractal Cloud is the process that bridges the Fractal Cloud control plane with your cloud environments through the installation of a Cloud Agent specialized for the cloud vendor you choose.
The control plane uses temporary credentials and has no direct access to your cloud environments. The Cloud Agent analyzes the drift between the declared infrastructure state (stored on the control plane) and the actual state of the provisioned cloud infrastructure, continuously resolving any differences.
One environment can have up to one agent per supported cloud vendor.
During initialization, Fractal Cloud creates and configures the resources required by the Cloud Agent in your cloud account, project, or subscription. After initialization, the Cloud Agent is responsible for reading cloud state, detecting drift, and reconciling managed resources.
Supported cloud providers
| Provider | Web UI initialization | Advanced initialization | Availability |
|---|---|---|---|
| Amazon Web Services (AWS) | Yes | Yes | General |
| Microsoft Azure | Yes | Yes | General |
| Google Cloud Platform (GCP) | Yes | Yes | General |
| Oracle Cloud Infrastructure (OCI) | Yes, Enterprise only | Yes | Enterprise |
| Hetzner Cloud | Yes, Enterprise only | Yes | Enterprise |
| IONOS Cloud | Yes, Enterprise only | Yes | Enterprise |
| Aruba Cloud | Yes, Enterprise only | Yes | Enterprise |
| Custom Agent for on-premises installations | Yes, Enterprise only | Yes | Enterprise |
Integration with OCI, Hetzner, IONOS, Aruba, and Custom Agent deployments is currently available for enterprise customers only.
Initialization methods
Fractal Cloud supports two initialization paths. Both create a Cloud Agent and connect it to the selected environment. Choose the path that best matches how your team operates.
| Method | Best for | Supported providers |
|---|---|---|
| Web UI initialization | Guided setup, first-time onboarding, interactive provider authorization, teams that prefer console-driven operations | AWS, Azure, GCP, OCI, Hetzner, IONOS, Aruba, Custom Agent |
| Advanced initialization | CI/CD pipelines, repeatable bootstrap flows, infrastructure automation, and restricted enterprise setups | AWS, Azure, GCP, OCI, Hetzner, IONOS, Aruba, Custom Agent |
If you are setting up a provider for the first time, start with the Web UI. If you need source-controlled, repeatable initialization, use the advanced path.
Web UI initialization
Use the Fractal Cloud Web UI when you want a guided setup flow. All supported providers can be initialized from the Web UI. Enterprise providers are shown in the same flow, but access may depend on your Fractal Cloud plan and enabled capabilities.
Before you start, make sure you have:
- A Fractal Cloud environment. If you do not have one yet, follow the Quick Start guide.
- Administrator-level access, or an equivalent bootstrap role, in the cloud account, project, or subscription you want to initialize.
- Permission to authorize Fractal Cloud against the selected provider.
Web UI flow
- Open your environment in the Fractal Cloud Web UI.
- Go to General, then find the Cloud Agents section.
- Select Initialize Cloud Agent.
- Choose the cloud provider you want to connect.
- Follow the provider authorization flow.
- Select the target account, project, subscription, or region when requested.
- Select Initialize to deploy the Cloud Agent.
After the process completes, the Cloud Agent appears in the environment page. From that point on, Fractal Cloud can deploy and reconcile components for that provider in the selected environment.
Provider authorization in the Web UI
The Web UI keeps the setup flow provider-native:
- AWS: authorize with IAM Identity Center when available, or use temporary STS credentials when your organization requires that model. You may need access to the target AWS account and the permission set used for initialization.
- Azure: use OAuth with Microsoft Entra ID when available, or use an Azure Service Principal for organizations that manage access through client credentials.
- GCP: authorize with Google Cloud, then select the GCP project where the Cloud Agent should be deployed.
The provider-specific pages explain the prerequisites and common setup issues:
For OCI, Hetzner, IONOS, Aruba, and Custom Agent deployments, follow the enterprise onboarding guidance provided by the Fractal Cloud team.
The Web UI does not ask you to paste long-lived provider credentials unless the selected provider flow requires an explicit credential-based alternative. Prefer the recommended OAuth or identity-center flow when it is available in your organization.
Advanced initialization
Advanced initialization is the programmatic path. Use it when initialization must be repeatable, reviewed, automated, or executed from a controlled environment such as a CI/CD pipeline.
You can initialize environments programmatically with:
- Java SDK: use the
environment-initializationsample. - TypeScript SDK: use the
fractal-ts-sdk-samplesrepository. - Terraform Provider: use the
terraform-provider-samplerepository.
Advanced flow
- Create or choose a Fractal Cloud environment and resource group.
- Prepare provider credentials for initialization.
- Follow the provider-specific guidance below.
- Run the SDK or Terraform initialization from your workstation, automation runner, or CI/CD pipeline.
- Store any automation credentials according to your organization's secret management policy.
The SDK checks if the environment exists in Fractal Cloud. If not, it creates the environment and all required Cloud Agent resources automatically.
Provider guides
| Provider | Advanced initialization guide |
|---|---|
| AWS | Create an initialization role and run the SDK flow |
| Azure | Create a Service Principal and run the SDK flow |
| GCP | Create a service account and run the SDK flow |
| OCI | Use the enterprise SDK flow |
| Hetzner | Use the enterprise SDK flow |
| IONOS | Enterprise onboarding with the Fractal Cloud team |
| Aruba | Enterprise onboarding with the Fractal Cloud team |
| Custom Agent | Enterprise onboarding for on-premises installations |
Do not manually modify or delete any Fractal Cloud Agent resources. To disconnect your environment from Fractal Cloud, use the UI or SDK to remove the environment. This also cleans up the Cloud Agent resources created in your cloud infrastructure.