diff --git a/userguide/aws/how-to-maintain-a-multi-tier-system.adoc b/userguide/aws/how-to-maintain-a-multi-tier-system.adoc index 82bb5f7db..ce4867fa9 100644 --- a/userguide/aws/how-to-maintain-a-multi-tier-system.adoc +++ b/userguide/aws/how-to-maintain-a-multi-tier-system.adoc @@ -12,7 +12,7 @@ This guide explains how to maintain your multi-tier Kill Bill installation on AW == Log in -To perform most maintenance tasks you will need to log in to your EC2 instances. Be sure that SSH is enabled on Port 22 in your security group. Login procedures are described in the setup guide (See https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system.html#_4_5_login_to_an_instance[4.5. Login to an Instance]). +To perform most maintenance tasks you will need to log in to your EC2 instances. Be sure that SSH is enabled on Port 22 in your security group. Login procedures are described in https://docs.killbill.io/latest/how-to-login-to-your-ec2-instance.html[How to Log In to Your EC2 Instance via SSH]. == Troubleshooting @@ -65,7 +65,7 @@ To access the RDS database, you can use the following command: `mysql -h -u -p` -Replace `` with the DB writer endpoint and `/` with the database credentials obtained during the setup (https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system#_2_2_create_the_database_manager[Step 2.2]). +Replace `` with the DB writer endpoint and `/` with the database credentials obtained during the setup (https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system#_2_2_create_the_rds_instance[Step 2.2]). include::{sourcedir}/aws/includes/database.adoc[] diff --git a/userguide/aws/how-to-set-up-a-multi-tier-system.adoc b/userguide/aws/how-to-set-up-a-multi-tier-system.adoc index faf6d609f..209df5168 100644 --- a/userguide/aws/how-to-set-up-a-multi-tier-system.adoc +++ b/userguide/aws/how-to-set-up-a-multi-tier-system.adoc @@ -3,7 +3,7 @@ :card-badge: Premium :card-title: AWS Deployment :card-link: https://aws.amazon.com/marketplace/pp/prodview-jvcsq4phzaclw -:card-description: +:card-description: include::{sourcedir}/includes/premium-card.adoc[] == Overview @@ -17,15 +17,29 @@ The diagram below shows the principal components of the multi-tier system: The E image::../assets/aws/multi-tier-ami_deployment.svg[width=750,align=center] -These components will be installed in reverse order. First we setup the RDS databases. Next the EC2 instances are created. Finally, the ELB load balancer is installed to tie everything together. +These components will be installed in reverse order. First we set up the RDS instance. Next the EC2 instances are launched, and the Kill Bill and Kaui databases are created on them. Finally, the ELB load balancer is installed to tie everything together. + +=== What You Will Need + +Before you begin, it helps to have the following ready: + +[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 + public subnet |EC2 instances and the load balancer need internet access |AWS VPC Console +|EC2 Key Pair |SSH access to EC2 instances |AWS EC2 Console (see Step 4) +|RDS database instance (MySQL/MariaDB/Aurora compatible) |Shared database for Kill Bill and Kaui |AWS RDS Console (see Step 2) +|TLS certificate |HTTPS on the load balancer |AWS Certificate Manager (see Step 7) +|=== The setup procedure includes eight steps: . <> -. <> +. <> . <> . <> -. <> +. <> . <> . <> . <> @@ -42,9 +56,9 @@ Check the upper right corner of your screen to be sure you are in the appropriat 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. [[step2]] -== Step 2: Setup the RDS +== Step 2: Set Up the RDS Instance -Once you are logged in, the first step is to setup the Relational Database System. This process begins with the RDS dashboard, which should be available from the Services menu. When the dashboard appears, select *Databases* from the left menu, and click the red button at the top right that reads *Create Database*: +Once you are logged in, the first step is to set up the Relational Database System. This process begins with the RDS dashboard, which should be available from the Services menu. When the dashboard appears, select *Databases* from the left menu, and click the red button at the top right that reads *Create Database*: image::../assets/aws/multitier-create-database.png[align=center] @@ -70,19 +84,19 @@ The last section asks you to: image::../assets/aws/multitier-names-and-password.png[align=center] -=== 2.2. Create the Database Manager +=== 2.2. Create the RDS Instance When the password is setup and confirmed, click *Create Database* in the lower right corner. You will return to the main Databases screen, which should now look like this: image::../assets/aws/multitier-database-starting.png[align=center] -This display shows that your database is starting. After a few minutes, the status will change to *Available* (You may need to reload the page to see this). You will also have a chance to see the password, in case it was autogenerated. Save this password, as you will need it later. +This display shows that your database instance is starting. After a few minutes, the status will change to *Available* (You may need to reload the page to see this). You will also have a chance to see the password, in case it was autogenerated. Save this password, as you will need it later. At this time you can click on the database name to get more information. You should see a panel named *Connectivity and Security*. The left side of this panel shows the full name of the endpoint, which you will need shortly, and the port number, which is normally 3306. image::../assets/aws/multitier-connectivity-and-security.png[align=center] -=== 2.3. Setup the Security Rules +=== 2.3. Set Up the Security Rules Lastly, on the *Connectivity and Security* panel, locate and click on the link for the default VPC security group. You will need to add an inbound security rule because the database by default does not allow external access. In the panel for this group, click on *Inbound Rules* and select *Edit Inbound Rules*. Next, click on *Add rule*. In the *Type* column select `MYSQL/Aurora`. The port will be set to 3306 automatically. In the *Source* column, click on the search icon and select `0.0.0.0/0`. Finally, click on *Save Rules* in the bottom right. Your database is ready to go. @@ -94,63 +108,7 @@ To ensure robust protection, it is essential to promptly update the database sec ==== [[step3]] -== Step 3: Create the Databases - -Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases. - -To create the databases, you will need to login to one of your instances as described above. Once you are logged in, you can use the `mysql` command to create the two databases `killbill` and `kaui`. The credentials required for this command are the same ones you set up for the database in step 2.1 above. - -Note that the host should *not* include the port number and there is no space after `-h` and `-u` options. - -The password will not be echoed when it is typed. - -[source,bash] ----- -> mysql -h -u -p -Enter Password: -mysql> create database killbill; -mysql> create database kaui; -mysql> exit ----- -The next step is to install the schemas. These can be found at: - -* killbill schema: `https://docs.killbill.io/latest/ddl.sql` -* kaui schema: `https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql` - -One easy way to do this is to return to your local computer (type `exit`) and download the schemas (give them distinct names), then use the `sftp` command to upload them to your EC2 instance home directory with the commands: - -[source,bash] ----- -sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP -put killbill.ddl -put kaui.ddl -exit ----- - -Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas: - -[source,bash] ----- -> mysql -h -u -p < killbill.ddl - -> mysql -h -u -p < kaui.ddl ----- -To ensure that the databases are setup correctly, login to `mysql` again, then try the SHOW TABLES command: - -[source,bash] ----- -> mysql -h -u -p - -use killbill; -show tables; -use kaui; -show tables; -exit ----- - - -[[step4]] -== Step 4: Edit the Configuration Script +== Step 3: Edit the Configuration Script To configure the EC2 instances and establish their connection to the databases, you'll need to provide essential information. Fortunately, Kill Bill and Kaui are equipped to read environment variables, making the setup more straightforward. For your convenience, we have a concise configuration script available to streamline this process. Below is the template for the script: @@ -234,13 +192,13 @@ The Kaui properties present in the provided template are required for proper fun Save this script to a file as it will be necessary during the launch of EC2 instances. -[[step5]] -== Step 5: Launch EC2 Instances +[[step4]] +== Step 4: Launch EC2 Instances The next step is to launch the number of EC2 instances you want, all based on the Kill Bill single AMI. -=== 5.1. Subscribe to the AMI +=== 4.1. Subscribe to the AMI To start the installation process, point your browser to the +++ @@ -259,7 +217,7 @@ Click *Continue to Subscribe*. The next page will give the AWS Terms and Conditi Accept the terms if asked. You will then see a new message confirming that you have subscribed. Next, click *Continue to Configuration*. -=== 5.2. Configure the Instances +=== 4.2. Configure the Instances The next page will give several configuration options: @@ -283,13 +241,13 @@ image::../assets/aws/single-tier-keypair.png[align=center] The key pair provides the credentials you will need to login to your EC2 instance. For details about key pairs, see the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS documentation]. We recommend that you create a new key pair. Click *Create Key Pair* to display a pane to be used for the creation. Give the key pair a simple, easy to remember name such as `My-Key-Pair`. Do not change the other options on this pane. Then click *Download Key Pair*. 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 instance. -=== 5.3. Setup Security Rules +=== 4.3. Set Up Security Rules The next step is to scroll down in the menu on the left side to select *Security Groups*. You should see a list of two or more groups. Select the group whose name begins with `Kill Bill on AWS`, then scroll to the bottom and select the tab for *Inbound Rules*. You should see: image::../assets/aws/multitier-inbound-original.png[align=center] -These rules enable the ports that must be open to access Kaui and Kill Bill from a browser. However, for access through the ELB these ports will be different. In addition, to enable direct login to your instance using SSH, you need to add one more port. +These rules enable the ports that must be open to access Kaui and Kill Bill from a browser. However, for access through the ELB these ports will be different. In addition, to enable direct login to your instance using SSH, which you will need in <> to create the databases, you need to add one more port. Click on *Edit Inbound Rules*. then do the following: @@ -302,20 +260,18 @@ Your Inbound Rules should now look like this: image::../assets/aws/multitier-inbound-new.png[align=center] -=== 5.4. Configure Network Settings +=== 4.4. Configure Network Settings -Before launching the instance, configure the network settings: +Before launching the instance, configure the network settings section: -* Select the VPC where you want to deploy the EC2 instance. -* Choose a *public subnet* within that VPC. -* Ensure *Auto-assign public IP* is *enabled*. +* Select the *VPC* where you want to deploy the EC2 instance. Every AWS account starts with a *default VPC*, and that default VPC already ships with a *public subnet* in every availability zone, so in most cases there is nothing to create here. A subnet is *public* when its route table has a route for destination `0.0.0.0/0` pointing to an *Internet Gateway* (target `igw-xxxxxxxx`), rather than to a NAT Gateway or no route at all. +* Ensure *Auto-assign public IP* is *enabled*. *This defaults to Disable* — without a public IP, you will not be able to reach the instance from the internet, nor log in to it over SSH. -This allows the instance to receive a public IP address and be accessible from the internet. If Auto-assign public IP is disabled or a private subnet is selected, you may not be able to access the instance without additional networking configuration. +=== 4.5. Add the User Data Script -=== 5.5. Add user data script -Finally, scroll to the bottom and open the section labeled *Advanced Details*. You will see a long list of settings. At the very bottom of this list is a box headed *User data*. Paste the script created in Step 4 here. +Finally, scroll to the bottom and open the section labeled *Advanced Details*. You will see a long list of settings. At the very bottom of this list is a box headed *User data*. Paste the script created in Step 3 here. -=== 5.6. Launch your Instances +=== 4.6. Launch Your Instances When the key pair is generated, click *Launch Instances*. You should see the screen below: @@ -328,21 +284,67 @@ image::../assets/aws/multitier-instances.png[align=center] In a short time, the *Instance State* for each instance should indicate *Running*. You will need to scroll to the right to see all of the information available about your instances. In particular, make a note of the *Availability Zone* (such as `us-east-1a`) assigned to each instance. You will need this information later. -=== 5.7. Login to an Instance +=== 4.7. Login to an Instance + +You will need to log in to one of your instances shortly, to create the Kill Bill and Kaui databases in <>. Logging in requires the SSH rule you added in section 4.3 above, and the same procedure applies across all of our AWS deployments, so it is described in a separate document: see https://docs.killbill.io/latest/how-to-login-to-your-ec2-instance.html[How to Log In to Your EC2 Instance via SSH]. + +NOTE: We recommend that you *remove* the SSH rule from your security group when you are *not* doing configuration or maintenance. + +[[step5]] +== Step 5: Create the Kill Bill and Kaui Databases + +Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases. + +To create the databases, log in to one of your instances as described in <> above. Once you are logged in, you can use the `mysql` command to create the two databases `killbill` and `kaui`. The credentials required for this command are the same ones you set up for the database in step 2.1 above. + +Note that the host should *not* include the port number and there is no space after `-h` and `-u` options. + +The password will not be echoed when it is typed. + +[source,bash] +---- +> mysql -h -u -p +Enter Password: +mysql> create database killbill; +mysql> create database kaui; +mysql> exit +---- +The next step is to install the schemas. These can be found at: + +* killbill schema: `https://docs.killbill.io/latest/ddl.sql` +* kaui schema: `https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql` -Now that your instances are set up, you need to ensure that you can login to them for configuration and maintenance when needed. To login, use the secure shell command: +One easy way to do this is to return to your local computer (type `exit`) and download the schemas (give them distinct names), then use the `sftp` command to upload them to your EC2 instance home directory with the commands: -`ssh -i .pem ubuntu@` +[source,bash] +---- +sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP +put killbill.ddl +put kaui.ddl +exit +---- -Here is the pathname where you have stored the private key that was downloaded when you generated your key pair, and is the IPV4 address for any one of your instances as described earlier. The private key will not work unless its access controls are set to readable by the owner only. +Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas: -On Windows versions before Windows 10, you may need to download a program called PuTTY to enable `ssh`. On Windows 10 `ssh` is available but may need to be activated through the Settings screen. +[source,bash] +---- +> mysql -h -u -p < killbill.ddl -The first time you login, you will see a warning message asking if you want to add this host to your list of hosts. You should answer `yes`. +> mysql -h -u -p < kaui.ddl +---- +To ensure that the databases are setup correctly, login to `mysql` again, then try the SHOW TABLES command: + +[source,bash] +---- +> mysql -h -u -p -You will now be able to explore your instance and perform various configuration and maintenance tasks. To exit from your login, type `exit`. +use killbill; +show tables; +use kaui; +show tables; +exit +---- -NOTE: [.no-title]#We recommend that you *remove* the SSH rule from your security group when you are *not* doing configuration or maintenance. [[step6]] == Step 6: Perform Initial Testing @@ -359,7 +361,7 @@ Repeat the tests for your other instance(s). You should also ensure that actions The last major task is to setup the Elastic Load Balancer in front of the EC2 instances. -=== 7.1. Select the ELB type +=== 7.1. Select the ELB Type To begin, from the EC2 dashboard scroll down the left-hand menu and select *Load Balancing / Load Balancers*. Then click the *Create Load Balancer* button at the upper left. @@ -371,7 +373,7 @@ In the section headed *Basic Configuration*, give your load balancer a name. Do In the *Network Mappings* section, select *at least two* availability zones. These *must* include the availability zones assigned to each of your EC2 instances (which you took note of earlier). -=== 7.3. Setup a Security Group +=== 7.3. Set Up a Security Group The next section is headed *Security Groups*. Click on *create new security group*. This will open a page headed *Create security group*. @@ -393,10 +395,10 @@ image::../assets/aws/ELB-secure-listener.png[align=center] Here you will be required to create or provide an X.509 SSL Certificate. If you already have a certificate you can identify it or upload it here. Otherwise click on *Request a New Certificate from ACM.* This will enable you to create a certificate using the *Amazon Certificate Manager*. Follow the steps described for the ACM in https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html[Add a Certificate Using the Amazon Certificate Manager], then return to this page. Select your new certificate from the dropdown list. You can now proceed to the next step. -Next you will need to click on *Add Listener* to create a second Listener. This listener will use port 8443. +Next you will need to click on *Add Listener* to create a second Listener. Just as with the first one, change its protocol to *HTTPS* and its port to `8443`, and select the same certificate from the dropdown list in the *Secure listener settings* section that opens up. -=== 7.5. Setup Target Groups +=== 7.5. Set Up Target Groups The next step is to identify the *target* instances for your load balancer, which are collected into a *target group*. Each listener will have a separate target group. Note that the display for each listener contains a link labeled *Create target group*. Click on this link for the first listener. This will setup the routing for messages directed to Kaui. @@ -427,4 +429,4 @@ When your ELB is complete you can proceed to testing. You should now be able to If these logins do not work correctly, review your setup steps carefully, then proceed to the https://docs.killbill.io/latest/how-to-maintain-a-multi-tier-system.html[Multi-Tier Maintenance Guide]. -Congratulations! Your multi-tier installation is ready to go! \ No newline at end of file +Congratulations! Your multi-tier installation is ready to go!