diff --git a/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc b/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc index 303179c38..82515216b 100644 --- a/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc +++ b/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc @@ -2,199 +2,309 @@ :card-badge: Premium :card-title: AWS Deployment -:card-link: https://aws.amazon.com/marketplace/pp/prodview-jvcsq4phzaclw -:card-description: +:card-link: https://aws.amazon.com/marketplace/pp/prodview-aicuarzg3e4t6 +:card-description: include::{sourcedir}/includes/premium-card.adoc[] == Overview -This document describes the procedures for setting up Kill Bill under AWS using the CloudFormation option. This is one of two recommended alternatives for production use. The multi-tier option requires more setup than CloudFormation, but provides more control over the deployment. The procedures in this document are based on the options recommended by Kill Bill. +Deploying Kill Bill via AWS CloudFormation is the fastest path to a production-grade installation. A single template creates and wires together all required AWS infrastructure automatically. -Deployment via CloudFormation leverages the capabilities of the AWS infrastructure to provide a robust *production ready* deployment with a single click. The entire CloudFormation configuration, or stack, is defined by a *CloudFormation Template*. - -The features of the CloudFormation system include: - -* The instance with Kill Bill and Kaui installed can be scaled up or down using an AWS Auto Scaling Group. -* AWS CloudWatch provides metrics to follow what is happening. -* The RDS database based on AWS Aurora comes automatically configured and ready for use. - -Running Kill Bill on AWS using our CloudFormation Template is the easiest and fastest way to get started with a production cluster. *It is also the only method of installation that is certified by the core developers for a highly available, horizontally scalable and production-ready installation.* - -With the click of a button, the template will install and configure: +image::../assets/aws/cf_stack.png[align=center] -* Kill Bill and Kaui on a custom AMI optimized for AWS workloads (integrated with CloudWatch, SQS, SES, X-Ray and more) -* Auto Scaling Groups, to automatically scale up and down the number of EC2 instances as needed (such as when batches of invoices are generated) -* A load balancer, integrated with our internal healthchecks to promptly take unhealthy instances out of rotation -* An RDS Aurora Cluster with automatic failover +The stack provisions: +* Kill Bill and Kaui on a custom AMI pre-configured for AWS (CloudWatch, SQS, SES, X-Ray) +* An Auto Scaling Group that scales EC2 instances up or down based on demand +* An Application Load Balancer with HTTPS on port 443 (Kaui) and port 8443 (Kill Bill API) +* An Aurora MySQL cluster across two availability zones with automatic failover -The following diagram shows the various AWS entities that will be created by CloudFormation: +*This is the only installation method certified by the Kill Bill core team for high availability, horizontal scalability, and production readiness.* -image::../assets/aws/cf_stack.png[align=center] +=== What You Will Need -All resources for this system run within a single AWS *Virtual Private Cloud (VPC)*, providing a dedicated block of IP addresses which must be located in a single *region*. The cloud is partitioned into *availability zones*, which are accessed by *subnets*. The resources must be distributed over at least two availability zones. +Collect the following before starting. Each item is covered in the <> section. -A single EC2 instance hosts both Kill Bill and Kaui servers in the VPC, running on an Ubuntu Linux server. AWS autoscaling is utilized to dynamically adjust the number of instances for each package based on demand, allowing for efficient scaling. +[cols="2,3,2", options="header"] +|=== +|Item |Purpose |Where to get it +|AWS account |All resources run in your account |https://aws.amazon.com +|VPC + 2 public subnets (min) |Load balancer and EC2 instances |AWS VPC Console +|2 private subnets (recommended) |Aurora RDS cluster, isolated from internet |AWS VPC Console +|TLS certificate ARN |HTTPS on the load balancer — *required before launch* |AWS Certificate Manager +|EC2 Key Pair |SSH access to EC2 instances |AWS EC2 Console +|=== -Access to these instances is managed by an AWS *Elastic Load Balancer (ELB)*. The ELB routes each request to the correct package and distributes the requests across the available instances. The ELB accepts traffic securely using HTTPS by default. +Estimated time: 30–45 minutes, most of which is unattended stack creation. -The back end of the system is an *Aurora* database manager provided through the AWS *Relational Database System (RDS)*. Aurora is a robust database system developed by AWS, compatible with MySQL and Postgres. There are separate databases maintained for Kill Bill and Kaui. +[[prerequisites]] +== Prerequisites -In addition, the complete CloudFormation system makes use of AWS scalable and reliable *S3* storage technology. +Complete each prerequisite once. They persist across stack re-creations and upgrades. -The procedures described here are based on the Kill Bill CloudFormation Template version 2022.10 or later. This system provides the framework for incorporating a variety of analytic tools, including Datadog, New Relic, Rollbar, Sentry, and AWS CloudWatch. In this How-To we will enable CloudWatch, which is easily integrated with our CloudFormation installation. We will *not* make use of the other analytic tools. +[[prereq-account]] +=== 1. AWS Account and Region -The setup procedure includes seven steps: +Log in to https://aws.amazon.com. Check the *region selector* in the upper-right corner of the console — all resources in the stack must be in the same region. Confirm you are in the correct region before proceeding. -. <> -. <> -. <> -. <> -. <> -. <> -. <> +[[prereq-vpc]] +=== 2. VPC and Subnets +The stack needs two sets of subnets within a single VPC: -[[step1]] -== Step 1: Login to AWS +* *EC2 and Load Balancer Subnets* (`Subnets` parameter): at least two *public* subnets, one per availability zone. The load balancer must be reachable from the internet. +* *RDS Database Subnets* (`RDSSubnets` parameter): at least two subnets for the Aurora cluster. For production, use *private* subnets (no route to the internet gateway) to isolate the database. -To begin, log in to Amazon Web Services at https://aws.amazon.com. If you are new to AWS, you will be asked to create an account and provide billing information. You will need to sign in as a *Root User*. This should take you to the *AWS Management Console*, which provides links to all available services. +To view or create subnets: *Services → Networking & Content Delivery → VPC → Subnets*. -Check the upper right corner of your screen to be sure you are in the appropriate *region*. All resources you create will be placed in this region, and may not be accessible from other regions. +AWS creates a default public subnet per availability zone automatically. For a quick test deployment you can use the same public subnets for both parameters. For production, create two dedicated private subnets for `RDSSubnets`. -In addition, AWS places all resources within a *Virtual Private Cloud (VPC)*. A default VPC will be created and used automatically in the following steps. However, if you have access to other VPCs, you will need to ensure that all Kill Bill resources are deployed in the same one. +You will need: -[[step2]] -== Step 2: Setup the VPC and Subnets +* Your VPC ID (`vpc-xxxxxxxx`) +* At least two subnet IDs for EC2/LB (`subnet-xxxxxxxx`) +* At least two subnet IDs for RDS (`subnet-xxxxxxxx`) -All resources for your CloudFormation deployment must be placed within a single VPC. To prepare for CloudFormation deployment you will first need to setup and identify your VPC and subnets. +[[prereq-cert]] +=== 3. TLS Certificate -=== 1. Setup your VPC +[IMPORTANT] +==== +The stack will fail immediately if `ELBListenerSSLCertARN` is empty or invalid. Create and copy the certificate ARN *before* launching the stack. +==== -From the *Services* menu item at the top of the main AWS page, under *Networking and Content Delivery*, select *VPC*. This will open the *VPC Dashboard*. Then select *Your VPCs* from the left menu. +The load balancer requires an HTTPS certificate stored in *AWS Certificate Manager (ACM)*. Two options: -Normally you will see one VPC, which AWS provides by default. This VPC will automatically be used for all your resources. If you have more than one, you need to select the one you want to use and be sure to set its ID as a parameter for your CloudFormation configuration. If there is no VPC listed, you must create one. The only parameter you need to set is the ipv4 CIDR block, which designates a range of (private) IP addresses. A suggested value is 192.168.0.0/16. +*Option A — ACM-issued certificate (production):* requires a domain name you control. AWS validates ownership via DNS CNAME, then issues the certificate automatically. Follow https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html[How to Add a Certificate Using ACM]. -=== 2. Setup your Subnets +*Option B — Imported self-signed certificate (testing):* avoids the need for a domain name. Browsers will show an untrusted certificate warning, which you can click through. -From the left menu of the VPC Dashboard select *Subnets*. This shows a list of your subnets. By default AWS creates one subnet for each Availability Zone in your region. You may create your own subnets, as long as you give each a CIDR block representing a unique subset of your VPC, and assign each to a specific availability zone. If you don't know what this means, just accept the defaults. +To generate a self-signed certificate: -[[step3]] -== Step3: Create a Certificate +[source,bash] +---- +openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \ + -days 365 -nodes \ + -subj "/CN=killbill.test.internal" \ + -addext "subjectAltName=DNS:killbill.test.internal" +---- -The CloudFormation implementation uses the HTTPS protocol for strong security. This requires the use of an X.509 certificate. +[IMPORTANT] +==== +The CN value must be a *fully-qualified domain name* — it must contain at least one dot. A value like `killbill-test` (no dot) will cause the load balancer listener to fail during stack creation with the error: _"The certificate must have a fully-qualified domain name."_ +==== -If you do not have a certificate, select *Security, Identity, and Compliance*, then *Certificate Manager* from the Services menu. Then follow the instructions in https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html[How to Add a Certificate Using ACM]. +Then import the certificate to ACM: *Services → Security, Identity & Compliance → Certificate Manager → Import*. -If you have a certificate created by ACM, you are all set. If you have a certificate not created by ACM, set the bottom left dropdown to **Import** and follow the instructions. Import the certificate to ACM. +After importing or creating the certificate, copy its ARN — it looks like: -Now select your certificate from the ACM list and copy its AWS Resource Name (ARN). Save this value as it will be needed in a later step. +---- +arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +---- +For background on how HTTPS, certificates, and the load balancer interact in this stack, see https://docs.killbill.io/latest/explanation-https-and-certificates.html[Explanation: HTTPS and Certificates]. -[[step4]] -== Step 4: Create a Key Pair +[[prereq-keypair]] +=== 4. EC2 Key Pair -The Kill Bill CloudFormation stack requires a key pair. The key pair provides the credentials you will need to login to your EC2 instances. If you already have a key pair, you are all set. Otherwise you will need to create one. +A key pair is required to SSH into EC2 instances. To create one: *EC2 Console → Network & Security → Key Pairs → Create Key Pair*. -To create a key pair, from the EC2 console scroll down to *Networks & Security / Key Pairs*. Select *Create Key Pair* and follow the instructions. Give the key pair a simple, easy to remember name such as `My-Key-Pair`.For details about key pairs, see the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS documentation]. Important: You *must* save the private key that will be generated in this step. If you lose this key, you will *not* be able to login to your instances. +[IMPORTANT] +==== +Download and save the private key file immediately. AWS will not let you download it again. If you lose it, you must create a new key pair and re-launch the stack. +==== -[[step5]] -== Step 5: Configure and Launch +== Step 1: Subscribe on AWS Marketplace -The setup process starts with the https://aws.amazon.com/marketplace/pp/prodview-aicuarzg3e4t6?sr=0-5&ref_=beagle&applicationId=AWSMPContessa[Kill Bill CloudFormation Template at AWS Marketplace]. Go to this page, then click *Continue to Subscribe*. +Go to the https://aws.amazon.com/marketplace/pp/prodview-aicuarzg3e4t6[Kill Bill CloudFormation Template on AWS Marketplace] and click *Continue to Subscribe*. image::../assets/aws/cf-subscribe.png[align=center] -THe next page gives the AWS Terms and Conditions. You must accept these conditions if asked, then click *Continue to Configuration*. This will take you to the page titled *Configure This Software*: +Accept the AWS terms and conditions when prompted, then click *Continue to Configuration*. + +On the *Configure This Software* page, verify your region is correct. Click *Continue to Launch*, then *Launch* on the next page. This opens the CloudFormation console. image::../assets/aws/cf-configure.png[align=center] -Make sure your Region is correct. There is nothing else to change on this page. Click *Continue to Launch*. THe next page is titled *Launch this Software*. There is nothing to do here either. Click *Launch*. +NOTE: The subscription and terms acceptance is a *one-time action per AWS account*. On subsequent deployments you go directly to the CloudFormation launch page. + +== Step 2: Launch the CloudFormation Stack -The next page is designated *Step 1: Specify Template* and titled *Create stack*: +The CloudFormation console opens at *Step 1: Specify Template*, with the template URL pre-filled. Click *Next*. image::../assets/aws/cf-step1.png[align=center] -Once again everything is filled in for you. Click *Next*. This brings up the *Stack Details* page (your complete configuration is called a stack): +On the *Specify stack details* page, enter a name for the stack (e.g. `killbill-prod`), then fill in the parameters below. Parameters are presented in four groups matching the form layout. image::../assets/aws/cf-details.png[align=center] -*Now* you have some work to do! This page requires that a number of configuration parameters be filled in. All of these are important, and some are critical. - -First, you need to provide a name for your stack. Any name will do, as long as it meets the stated rules. Then you will need to carefully set a series of parameters: - -* *CloudWatchMetricsLevel:* the amount of metrics that will be collected for CloudWatch. No change needed. -* *DBClass:* the database instance type to use for RDS. This normally should not be changed. -* *DBName:* the database name for Kill Bill. This is preset to *killbill*. Do not change it. -* *DBPassword:* database admin password. The password you choose for the database administrator. This must be at least 8 characters long, and composed entirely of letters and digits. -* *DBUser:* database admin username. The username you choose for the database administrator. -* *DatadogApiKey:* the key needed if using Datadog. Leave blank. -* *ELBListenerSSLCertARN:* the ARN for the certificate you setup in Step 3. -* *EnableCloudWatchMetrics:* whether to enable metrics in CloudWatch. Leave set to true. -* *EnableDatadog:* leave set to false. -* *EnableNewRelic:* leave set to false. -* *EnableRollbar:* leave set to false. -* *EnableSentry:* leave set to false. -* *EnvType:* the purpose of this configuration: test, dev (development), or prod (production). There is no difference in the stack being created but this value will be sent to CloudWatch as a dimension. -* *HTTPLocation:* the IP address range allowed to access the load balancer, in the form of a CIDR block. You can use 0.0.0.0/0 initially and adjust access later on. -* *InstanceType:* the EC2 instance type to use for Kill Bill. This normally should not be changed. -* *KBAdminPassword:* the password to be used for the default `root` user which has all permissions. By default this is set to `password`. Please change it! There are currently no restrictions on format. This is also the password you will use to login to Kaui. -* *KauiDBName:* database name for Kaui. This is preset to *kaui*. Do not change it. -* *KeyName:* name of your existing EC2 KeyPair to enable SSH access to the instances. You created this in Step 4. -* *KillBillServerCapacity:* the initial number of Kill Bill instances in the Auto Scaling group. Again we recommend the default value of `2`. -* *NewRelicApiKey:* key needed if New Relic is used. Leave blank. -* *RDSSubnets:* the subnets to use for the RDS instance. Select two or more from your subnets, which must be in two or more availability zones. There is no harm in using more. -* *RollbarAccessToken:* key needed for Rollbar. Leave blank. -* *SentryDsn:* key needed for Sentry. Leave blank. -* *SetEnvironmentVariables:* A comma-delimited list of environment variables to set. -* *SsmStorePath:* SSM parameter store that can be used for key pairs. Leave this blank. -* *Subnets:* the subnets to use for the KB and Kaui instances. Also two or more from your subnets in two or more availability zones. These may or may not be the same as the RDS subnets. -* *VpcId:* the Id of the VPC to use for the installation, which you identified earlier. - -When all of these are set, click *Next* to go to *Configure Stack Options*. There is only one thing to do here. Scroll down to the panel labeled *Stack Failure Options*, and select the option *Preserve Successfully Provisioned Resources.* This ensures that if your stack creation fails, you can use the resources that were successfully created to help troubleshoot the problem. Then click *Next*. +[[params-network]] +=== Required: Network Configuration + +[cols="2,4", options="header"] +|=== +|Parameter |What to enter +|*VPC ID* |Your VPC ID from <> (e.g. `vpc-0abc12345`) +|*EC2 and Load Balancer Subnets* |Select at least 2 public subnets across 2 AZs +|*RDS Database Subnets* |Select at least 2 subnets across 2 AZs (private subnets recommended for production) +|=== + +[[params-security]] +=== Required: Security + +[cols="2,4", options="header"] +|=== +|Parameter |What to enter +|*TLS Certificate ARN* |The ARN copied from ACM in <>. Must start with `arn:aws:acm:`. +|*Allowed IP Range for Load Balancer* |CIDR controlling who can reach the load balancer. Use `0.0.0.0/0` initially; restrict to your IP range for production. +|*Kill Bill / Kaui Admin Password* |Password for the `admin` user. Minimum 8 characters. You will use this to log in to Kaui after deployment. +|*Database Username* |Admin username for Aurora. Letters and digits only; must start with a letter. +|*Database Password* |Admin password for Aurora. Minimum 8 characters, letters and digits only. +|*EC2 Key Pair Name* |Name of the key pair from <>. +|=== + +[[params-capacity]] +=== Optional: Capacity and Environment + +These have sensible defaults. Change only if you have a specific reason. + +[cols="2,3,1,2", options="header"] +|=== +|Parameter |Description |Default |Guidance +|*Environment Type* |Labels CloudWatch metrics as prod/test/dev |`test` |Set to `prod` for production deployments +|*EC2 Instance Type* |Compute size for Kill Bill instances |`t2.medium` |Increase for sustained high traffic +|*Initial Number of EC2 Instances* |Starting capacity in the Auto Scaling Group |`2` |`1` is sufficient for testing +|*RDS Instance Class* |Database compute size |`db.t3.medium` |Increase for high write/read load +|=== + +[[params-monitoring]] +=== Optional: Monitoring and Observability + +CloudWatch is enabled by default. Third-party integrations are opt-in. + +[cols="2,3,1", options="header"] +|=== +|Parameter |Description |Default +|*Enable CloudWatch Metrics* |Sends metrics to AWS CloudWatch |`true` +|*CloudWatch Metrics Detail Level* |Amount of data: NONE / MINIMAL / LARGE / ALL |`MINIMAL` +|*Enable New Relic / Datadog / Sentry / Rollbar* |Third-party observability integrations |`false` +|*API keys for each tool* |Required only if the corresponding tool is enabled |blank +|=== + +=== Advanced Settings + +*Do not change these parameters unless explicitly instructed.* + +[cols="2,3", options="header"] +|=== +|Parameter |Description +|*Kill Bill Database Name* |Preset to `killbill` — changing this breaks the schema setup +|*Kaui Database Name* |Preset to `kaui` — changing this breaks the schema setup +|*Kill Bill AMI ID* |Pre-set to the current certified AMI — changing this will break the deployment +|*SSM Parameter Store Path* |For config stored in SSM. Leave blank. +|*Custom Environment Variables* |Comma-delimited list of env vars. Leave blank unless instructed. +|=== + +=== Configure Stack Options and Submit + +Click *Next* to reach *Configure stack options*. Scroll to *Stack failure options* and select *Preserve Successfully Provisioned Resources*. This allows you to inspect partial deployments for troubleshooting. image::../assets/aws/cf-failure-options.png[align=center] - -The final page gives you a chance to review. If everything seems OK, read and check any warnings at the bottom, then click *Submit*. you are off! +Click *Next*, review the summary, check any capability acknowledgement boxes at the bottom, and click *Submit*. image::../assets/aws/cf-creating.png[align=center] -If there are any errors, you will see a message and the Create will not begin. You will need to go back and fix the errors. Common errors may include using an invalid password form (which may give a misleading message), or not choosing subnets in at least two availability zones. +Stack creation takes 15–25 minutes. The status shows `CREATE_IN_PROGRESS` (blue) while running and `CREATE_COMPLETE` (green) when done. Watch individual resources on the *Events* and *Resources* tabs. + +If the status changes to `CREATE_FAILED`, see <> below. + +== Step 3: Verify Your Deployment + +Once the stack status is `CREATE_COMPLETE`, open the *Outputs* tab and copy the *WebsiteURL* value — this is the ALB DNS name. -Otherwise, you will see that your stack is being created, and its status (shown in blue) will be `CREATE_IN_PROGRESS`. You may also check the *Resources* tab to see the many resources that are being created to make up the complete stack. +Open the Kaui login page in your browser: -If the create succeeds, the status will eventually change to `CREATE_COMPLETE` (shown in green). This may take a fairly long time. +---- +https:///users/sign_in +---- + +If you imported a self-signed certificate, your browser will display a security warning. Click through it to proceed. + +image::../assets/aws/cf-kaui.png[align=center] -[[step6]] -== Step 6: Setup a CNAME +Log in with: -A critical resource included in your CloudFormation implementation is the ELB Load Balancer. To complete the protection of this resource by your certificate, as explained in https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html[How to Add a Certificate Using ACM], you need to create a CNAME for your domain with the name "kaui" and a value that points to this load balancer. +* *Username:* `admin` +* *Password:* the *Kill Bill / Kaui Admin Password* you set in the stack parameters -First, find the load balancer in the EC2 console: +For a guided introduction to Kaui, see the https://docs.killbill.io/latest/quick_start_with_kaui.html[Quick Start with Kaui]. + +To access the Kill Bill API and Swagger documentation directly: + +---- +https://:8443 +---- + +== Step 4: (Optional) Configure DNS + +If you used an ACM-issued certificate for a domain you own, create a DNS CNAME at your domain registrar pointing your subdomain to the ALB DNS name: + +---- +kaui.mycompany.com → .us-east-1.elb.amazonaws.com +---- + +To find the ALB DNS name: *EC2 Console → Load Balancers*, select your load balancer, and copy the *DNS name* field. image::../assets/aws/cf-elb.png[align=center] -Select the load balancer and copy its DNS name as the value for the CNAME you are creating. +NOTE: This routing CNAME is *separate* from the ACM certificate validation CNAME. The validation CNAME proves domain ownership to AWS during certificate issuance. The routing CNAME directs traffic to your stack. They have different names and serve different purposes — you need both if you used an ACM-issued certificate. +Once the CNAME propagates (typically a few minutes to an hour depending on your DNS TTL), access Kaui at `\https://kaui.mycompany.com`. -[[step7]] -== Step 7: Test your Stack +[[troubleshooting]] +== Troubleshooting -You should now be able to login to Kaui from your browser using the URL `\https://kaui.:9090`, where is *your* domain that you have used for your certificate. The Kaui login screen should appear: +=== `KBLBListener` or `KauiLBListener` fails: "Certificate ARN is not valid" -image::../assets/aws/cf-kaui.png[align=center] +The `ELBListenerSSLCertARN` parameter was empty or malformed. The load balancer requires a valid certificate ARN at creation time. + +*Fix:* Delete the failed stack. Complete <> to create and import a certificate in ACM, then re-launch with the ARN filled in. + +=== `KauiLBListener` fails: "certificate must have a fully-qualified domain name" + +The imported certificate's Common Name (CN) does not contain a dot (e.g. `killbill-test` instead of `killbill.test.internal`). The ALB rejects certificates without a proper FQDN. + +*Fix:* Regenerate the certificate with an FQDN CN: + +[source,bash] +---- +openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \ + -days 365 -nodes \ + -subj "/CN=killbill.test.internal" \ + -addext "subjectAltName=DNS:killbill.test.internal" +---- + +Delete the old certificate from ACM, import the new one, delete the failed stack, and re-launch. + +=== Login fails via the load balancer URL but works via EC2 IP directly +Logging in to Kaui returns to the sign-in page repeatedly, but accessing the EC2 instance directly by IP works. This is a Rails trusted proxy configuration issue: when traffic arrives through the ALB, Rails does not recognize the ALB as a trusted proxy and refuses to set the secure session cookie. -For an introduction to Kaui, see our https://docs.killbill.io/latest/quick_start_with_kaui.html[Quick Start with Kaui] guide. The default credentials are: `admin` / ``, where is the parameter *KBAdminPassword* that you set earlier. +See https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system[How to Maintain a CloudFormation System] for the fix. -Similarly, you should be able to login directly to the Kill Bill server using the URL `\https://kaui.`. -This provides access to certain detailed resources that may be needed for maintenance, including metrics and the Swagger API pages. +=== Stack creation times out at `KBAutoScalingGroup` +The EC2 instances failed to signal CloudFormation within the 15-minute window. This usually means the instance initialization script encountered an error. -Congratulations! Your CloudFormation installation is ready to go! +To diagnose: -For information on troubleshooting, maintaining and upgrading your installation see https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system[How to Maintain a CloudFormation System]. +. Go to *EC2 Console → Instances*, find the Kill Bill instance +. Choose *Actions → Monitor and Troubleshoot → Get System Log* to see the boot output +. Check the *Events* tab on the CloudFormation stack for the specific failing step +Common causes: the RDS cluster was not reachable from the EC2 instances (check security groups and subnet routing), or an invalid parameter value was passed to the install script. +--- +For maintenance, scaling, upgrades, and ongoing operations, see https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system[How to Maintain a CloudFormation System].