You’ve decided that Spacelift’s offering of a self-hosted platform in AWS is exactly what you need. Great — now let’s get it set up for you!
In this post, we will take you through all the steps you need to take to install the platform. Let’s get started:
After you contact our team, your license will be delivered to AWS License Manager in the AWS account and region where you will run the Spacelift platform.
If you have never used AWS License Manager, you will need to activate the service. This is a quick, easy process. Navigate to AWS License Manager service:
Click “Start using AWS License Manager”.
You will be asked for confirmation. After that, AWS License Manager will be enabled. There is no additional cost for the service itself; you pay only for resources you create to run the application.
When the license is delivered to your AWS account, accept and activate it.
That’s the license sorted! Now it is time to prepare an AWS account for installation of the service.
Ensure you are ready to install the Spacelift Self-Hosted platform on your AWS account. You need to run a few steps on the AWS side, and you must also have all the required software installed on the machine from which you will run the installer.
- You need to have a Linux or MacOS machine, from where you will initialize the installation process.
- You must have default tooling on this machine and also Docker and jq.
- You must install and configure AWS CLI v2.
- You should prepare the SSL certificate, using AWS Certificates Manager. This certificate must be created for the domain you will use with the Spacelift Self-Hosted platform.
Now that everything is ready, it is time to install the platform. First, you have to unpack the bundle file. You should do it with good old tar:
$> tar -zxf <package>.tar.gz
Please note that some differences are possible, depending on the package version.
When the package is unpacked, edit the config.json file according to our documentation.
SSO configuration
A critical element in this process is to provide proper authentication configuration. You can configure either SAML or OIDC authentication. If you don’t have either, you can do so with Azure AD, AWS IAM Identity Center (formerly AWS SSO), OKTA, or a range of other options.
Every provider has its own dashboard. However, the general rule is you must have an application configured in your SSO system for Spacelift authentication. In this post, I’m going to use AWS IAM Identity Center for SSO.
The following screenshot shows an application called “Spacelift Self-Hosted” I configured in Identity Center.
In the example below I configured AWS IAM Identity Center, using non-dynamic metadata.
This metadata file needs to be downloaded from the SSO provider. Simply, click the “Download” link in the “IAM Identity Center metadata” tab.
In the config file, you need to provide a valid JSON-escaped string, so the metadata file needs to be modified. If the metadata file is saved as “metadata.xml”, do it with this command:
$> cat metadata.xml | jq -R -s '.'Now you can add all pieces to the config.json file.
In the example below, you can find my sample configured for AWS IAM Identity Center:
“sso_config”: {
“admin_login”: “<email>”,
“sso_type”: “SAML”,
“saml_args”: {
“metadata”: “<here goes the escaped metadata we just created>”,
“dynamic”: false,
“name_id_format”: “TRANSIENT”
}
}In the case of AWS IAM Identity Center, I had to add Attribute mappings for my application.
If this is the case for you too, below is an example how to do it in AWS.
Useful hint for tags
A handy hint: We all know how crucial it is to tag and then control resources we create. One of the many reasons for this is cost tracking. Another is to know the kind and number of resources out there. To comfortably track all resources created for the Spacelift platform, you can add tags in the “global_resource_tags” section in config.json. This is very convenient.
As an example, I added:
“global_resource_tags” : [
{
“key”: “ platform”,
“value”: “Spacelift”
},
{
“key”: “type”,
“value”: “self-hosted”
}
]Run installer
You are now ready to run the installer.
$> ./install.shAnd that’s it! Now sit back and watch the installation process.
The installation contains many CloudFormation stacks. These stacks prepare all resources needed to run the main part of the Spacelift Self-Hosted platform. All actions are visible on your screen so you can control the progress.
Having so many stacks facilitates modular construction. When needed, it will be easier to provide a custom stack for a specific case (for example, VPC, Database, or ECS)
When the installer finishes, the main part of Spacelift is installed. You can see the AWS ECS Fargate cluster is up and ready to work.
The last thing for this part of installation is to create a DNS entry. In the preparation section, you created the SSL certificate using AWS Certificate Manager. Now, you need to create an alias in Route53 and point it to the load balancer created during the installation.
For your convenience, the ARN (unique identifier of the resource in AWS) of this load balancer is available as output from the installation script. Look for the “Load balancer DNS” position.
When it is ready, you can log in to your Spacelift on AWS! Simply open your browser and provide the DNS name you just created.
Do you remember when I mentioned the “global_resource_tags”? If you create a group in AWS Resource Groups, you can see all related resources created for the platform.
The main installation is complete, so now it is time to add workers to the stack. Remember that this process is a little different to adding worker pools to the SaaS platform. The documentation describes the process, but it requires some manual steps.
Generate OpenSSL key
Follow the instructions here and prepare the key.
Establish new worker pool
Follow the instructions to create a new worker pool and add the csr file to it. You will receive the config file for your pool. Save it.
Create a Secret
The next step is also manual. You have to create a secret in the AWS Secret Manager. There are two keys to create. The SPACELIFT_TOKEN is the string you received in the config file. For SPACELIFT_POOL_PRIVATE_KEY you have to encode the *.key file using base64 utility. This step is described here.
Run the CloudFormation template
And now it is time to run the CloudFormation template! You must provide some parameters, for example, AMI of the image. You don’t need to create this image yourself. Here is an up-to-date list of AMIs provided by Spacelift.
And, just like that, your worker pool is ready!
The last step is to configure the connection to your Version Control System and your target cloud account. Now you are ready to fly!
Installing Spacelift Self-Hosted on AWS is neither time-consuming nor complicated. After a few preparatory steps, execution of one script and, separately, one CloudFormation template for the worker pool, you have a fully functional platform deployed on your AWS account. You can find more details in our documentation.
The self-hosted setup on AWS is the answer when SaaS solutions won’t work. With this option we help you to comply with your specific governance, security and regulatory requirements. But you also have the option to modify the setup according to your needs.
Whether it’s a self-hosted setup on AWS or our SaaS platform, talk to our sales team or book a demo to find out how we can help you streamline your IaC management.
The most flexible management platform for Infrastructure as Code
Spacelift is a sophisticated SaaS product for Infrastructure as Code that helps DevOps develop and deploy new infrastructures or changes quickly and with confidence.
