diff --git a/docs/assets/images/screenshots/subnet-cidr-calculator.png b/docs/assets/images/screenshots/subnet-cidr-calculator.png new file mode 100644 index 00000000..63219eb8 Binary files /dev/null and b/docs/assets/images/screenshots/subnet-cidr-calculator.png differ diff --git a/docs/try-leverage/add-aws-accounts.md b/docs/try-leverage/add-aws-accounts.md index c02dfce8..480604d3 100644 --- a/docs/try-leverage/add-aws-accounts.md +++ b/docs/try-leverage/add-aws-accounts.md @@ -25,7 +25,17 @@ You can add new AWS accounts to your Leverage project by following the steps in leverage terraform init leverage terraform apply ``` -4. Add the new account to the `config/common.tfvars` file. The new account ID should have been displayed in the output of the previous step so please grab it from there and use it to update said file as in the example below: +!!! info "Authentication error" + Note this layer was first applied before using the boostrap user. Now, that we are working with SSO, credentials have changed. So, if this is the first account you add you'll probably get this error applying: "Error: error configuring S3 Backend: no valid credential sources for S3 Backend found." + In this case running `leverage tf init -reconfigure` will fix the issue. + +4. Add the new account to the `/config/common.tfvars` file. The new account ID should have been displayed in the output of the previous step, e.g.: + ```shell + aws_organizations_account.accounts["apps-prd"]: Creation complete after 14s [id=999999999999] + ``` + **Note** the id, `999999999999`. + + ...so please grab it from there and use it to update the file as shown below: ```shell accounts = { @@ -37,34 +47,29 @@ You can add new AWS accounts to your Leverage project by following the steps in } } ``` -5. If you are using SSO in this project, permissions on the new account must be granted before we can move forward. Add the right permissions to the `management/global/sso/account_assignments.tf` file. For the example: +5. Since you are using SSO in this project, permissions on the new account must be granted before we can move forward. Add the right permissions to the `management/global/sso/account_assignments.tf` file. For the example: ```yaml - { - account = var.accounts.apps-prd.id, - permission_set_arn = module.permission_sets.permission_sets["Administrator"].arn, - permission_set_name = "Administrator", - principal_type = "GROUP", - principal_name = "AWS_Administrators" - }, - - { - account = var.accounts.apps-prd.id, - permission_set_arn = module.permission_sets.permission_sets["DevOps"].arn, - permission_set_name = "DevOps", - principal_type = "GROUP", - principal_name = "AWS_DevOps" - }, - - { - account = var.accounts.apps-prd.id, - permission_set_arn = module.permission_sets.permission_sets["Developer_FullAccess"].arn, - permission_set_name = "Developer_FullAccess", - principal_type = "GROUP", - principal_name = "AWS_Developers" - }, + # ------------------------------------------------------------------------- + # apps-prd account + # ------------------------------------------------------------------------- + { + account = var.accounts.apps-prd.id, + permission_set_arn = module.permission_sets.permission_sets["Administrator"].arn, + permission_set_name = "Administrator", + principal_type = local.principal_type_group + principal_name = local.groups["administrators"].name + }, + { + account = var.accounts.apps-prd.id, + permission_set_arn = module.permission_sets.permission_sets["DevOps"].arn, + permission_set_name = "DevOps", + principal_type = local.principal_type_group + principal_name = local.groups["devops"].name + }, + ``` + Note your needs can vary, these permissions are just an example, please be careful with what you are granting here. - ``` - Note your needs can vary, these permissions are just an example, please be careful with what you are granting here. Apply these changes: + Apply these changes: ```shell leverage terraform apply ``` @@ -76,7 +81,7 @@ You can add new AWS accounts to your Leverage project by following the steps in Good! Now you are ready to create the initial directory structure for the new account. The next section will guide through those steps. ## Create and deploy the layers for the new account -In this example we will create the `apps-prd` account structure by using the `apps-devstg` as a template. +In this example we will create the `apps-prd` account structure by using the `shared` as a template. ### Create the initial directory structure for the new account 1. Ensure you are at the root of this repository @@ -87,44 +92,35 @@ In this example we will create the `apps-prd` account structure by using the `ap 3. Set up the config files: 1. Create the config files for this account: ```shell - cp -r apps-devstg/config apps-prd/config + cp -r shared/config apps-prd/config ``` - 2. Open `apps-prd/config/backend.tfvars` and replace any occurrences of `devstg` with `prd`. (basically, `apps-devstg` is being replaced with the new name `apps-prd`) + 2. Open `apps-prd/config/backend.tfvars` and replace any occurrences of `shared` with `apps-prd`. 3. Do the same with `apps-prd/config/account.tfvars` - 4. If **no SSO** is implemented in the project (i.e. OAAR is being used): - 1. Open up `apps-prd/config/backend.tfvars` again and replace this: - ```yaml - profile = "bb-apps-prd-devops" - ``` - with this: - ```yaml - profile = "bb-apps-prd-oaar" - ``` - 2. In the step above, we are switching to the OAAR (OrganizationalAccountAccessRole) role because we are working with a brand new account that is empty, so, the only way to access it programmatically is through the OAAR role. - 3. Now it's time to configure your OAAR credentials (if haven't already done so). For that you can follow the steps in [this section](https://leverage.binbash.co/try-leverage/management-account/#update-the-bootstrap-credentials) of the official documentation. ### Create the Terraform Backend layer 1. Copy the layer from an existing one: ```shell - cp -r apps-devstg/us-east-1/base-tf-backend apps-prd/us-east-1/base-tf-backend + cp -r shared/us-east-1/base-tf-backend apps-prd/us-east-1/base-tf-backend ``` !!! info - If the source layer was already initialized you should delete the previous Terraform setup using `sudo rm -rf .terraform*` in the target layer's directory. + If the source layer was already initialized you should delete the previous Terraform setup using `sudo rm -rf .terraform*` in the target layer's directory, e.g. `rm -rf apps-prd/us-east-1/base-tf-backend/.terraform* ` 2. Go to the `apps-prd/us-east-1/base-tf-backend` directory, open the `config.tf` file and comment the S3 backend block. E.g.: ```yaml #backend "s3" { - # key = "apps-devstg/tf-backend/terraform.tfstate" + # key = "shared/tf-backend/terraform.tfstate" #} ``` + We need to do this for the first apply of this layer. + 3. Now run the [Terraform workflow](https://leverage.binbash.co/user-guide/ref-architecture-aws/workflow/) to initialize and apply this layer. The flag `--skip-validation` is needed here since the bucket does not yet exist. ```shell leverage terraform init --skip-validation leverage terraform apply ``` -4. Open the `config.tf` file again uncommenting the block commented before and replacing `devstg` with `prd`. E.g.: +4. Open the `config.tf` file again uncommenting the block commented before and replacing `shared` with `apps-prd`. E.g.: ```yaml backend "s3" { key = "apps-prd/tf-backend/terraform.tfstate" @@ -148,39 +144,17 @@ In this example we will create the `apps-prd` account structure by using the `ap ``` Enter `yes` and hit enter. -### Create the identities layer -1. Copy the layer from an existing one: - From the repository root run: - ```shel - cp -r apps-devstg/global/base-identities apps-prd/global/base-identities` - ``` -2. Go to the `apps-prd/global/base-identities` directory and open the `config.tf` file. Replace any occurrences of `devstg` with `prd`. E.g. this line should be: - ```yaml - backend "s3" { - key = "apps-prd/identities/terraform.tfstate" - } - ``` -3. Init the layer - ```shell - leverage tf init -reconfigure -upgrade - ``` -4. Import the OAAR role - Run this command: - ```shell - leverage tf import module.iam_assumable_role_oaar.aws_iam_role.this OrganizationAccountAccessRole - ``` -5. Finally apply the layer - ```shell - leverage tf apply - ``` - ### Create the `security-base` layer 1. Copy the layer from an existing one: From the repository root run: ```shell - cp -r apps-devstg/us-east-1/security-base apps-prd/us-east-1/security-base + cp -r shared/us-east-1/security-base apps-prd/us-east-1/security-base ``` -2. Go to the `apps-prd/us-east-1/security-base` directory and open the `config.tf` file replacing any occurrences of `devstg` with `prd` + + !!! info + If the source layer was already initialized you should delete the previous Terraform setup using `sudo rm -rf .terraform*` in the target layer's directory, e.g. `rm -rf apps-prd/us-east-1/security-base/.terraform* ` + +2. Go to the `apps-prd/us-east-1/security-base` directory and open the `config.tf` file replacing any occurrences of `shared` with `apps-prd` E.g. this line should be: ```yaml backend "s3" { @@ -190,7 +164,7 @@ In this example we will create the `apps-prd` account structure by using the `ap 3. Init and apply the layer ```shell - leverage tf init -reconfigure -upgrade + leverage tf init leverage tf apply ``` @@ -198,9 +172,13 @@ In this example we will create the `apps-prd` account structure by using the `ap 1. Copy the layer from an existing one: From the root of the repository run this: ```shell - cp -r apps-devstg/us-east-1/base-network apps-prd/us-east-1/base-network + cp -r shared/us-east-1/base-network apps-prd/us-east-1/base-network ``` -2. Go to the `apps-prd/us-east-1/base-network` directory and open the `config.tf` file replacing any occurrences of `devstg` with `prd`. E.g. this line should be: + + !!! info + If the source layer was already initialized you should delete the previous Terraform setup using `sudo rm -rf .terraform*` in the target layer's directory, e.g. `rm -rf apps-prd/us-east-1/base-network/.terraform* ` + +2. Go to the `apps-prd/us-east-1/base-network` directory and open the `config.tf` file replacing any occurrences of `shared` with `apps-prd`. E.g. this line should be: ```yaml backend "s3" { key = "apps-prd/network/terraform.tfstate" @@ -233,18 +211,27 @@ In this example we will create the `apps-prd` account structure by using the `ap ] ``` Note here only two AZs are enabled, if needed uncomment the other ones in the three structures. + + !!! warning "Do not overlap CIDRs!" + Be careful when chosing CIDRs. + Avoid overlaping CIDRs between accounts. + If you need a reference on how to chose the right CIDRs, please see [here](/user-guide/ref-architecture-aws/features/network/vpc-addressing/). + + !!! info "Calculate CIDRs" + To calculate CIDRs you can check [this playbook](/user-guide/playbooks/VPC-subnet-calculator/). + 3. Init and apply the layer ```shell - leverage tf init -reconfigure -upgrade + leverage tf init leverage tf apply ``` + 4. Create the VPC Peering between the new account and the VPC of the Shared account. Edit file `shared/us-east-1/base-network/config.tf` and add provider and remote state for the created account. ```yaml provider "aws" { alias = "apps-prd" region = var.region profile = "${var.project}-apps-prd-devops" - shared_credentials_file = "~/.aws/${var.project}/config" } data "terraform_remote_state" "apps-prd-vpcs" { @@ -272,6 +259,9 @@ In this example we will create the `apps-prd` account structure by using the `ap ``` ...add the related structure: ```yaml + # + # Data source definitions + # apps-prd-vpcs = { apps-prd-base = { region = var.region @@ -282,13 +272,13 @@ In this example we will create the `apps-prd` account structure by using the `ap } } ``` - Edit file `shared/us-east-1/base-network/vpc_peerings.tf` and add the peering definition: + Edit file `shared/us-east-1/base-network/vpc_peerings.tf` (if this is your first added account the file won´t exist, please crate it) and add the peering definition: ```yaml # # VPC Peering: AppsPrd VPC => Shared VPC # module "vpc_peering_apps_prd_to_shared" { - source = "github.com/binbashar/terraform-aws-vpc-peering.git?ref=v4.0.1" + source = "github.com/binbashar/terraform-aws-vpc-peering.git?ref=v6.0.0" for_each = { for k, v in local.apps-prd-vpcs : @@ -321,30 +311,26 @@ In this example we will create the `apps-prd` account structure by using the `ap ``` Apply the changes (be sure to CD into `shared/us-east-1/base-network` layer for doing this): ```shell + leverage terraform init leverage terraform apply ``` -### Replace temporary profiles with permanent ones -1. If no SSO is implemented in the project (i.e. OAAR is being used), switch back from OAAR to DevOps role -2. Open up `apps-prd/config/backend.tfvars`and replace this: - ```yaml - profile = "bb-apps-prd-oaar" - ``` - with this: - ```yaml - profile = "bb-apps-prd-devops" - ``` - This is needed because we only want to use the OAAR role for exceptional cases, not on a daily basis. -3. Now, let's configure your DevOps credentials (if you haven't already done so). - 1. Log into your security account, create programmatic access keys, and enable MFA. - 2. Then run: `leverage credentials configure --fetch-mfa-device --type SECURITY` - 3. The command above should prompt for your programmatic keys and, with those, Leverage should be able to configure your AWS config and credentials files appropriately. - ## Done! That should be it. At this point you should have the following: 1. A brand new AWS account in your AWS organization. 2. Working configuration files for both existing layers and any new layer you add in the future. 3. A remote Terraform State Backend for this new account. -4. Roles and policies (base identities) that are necessary to access the new account. +4. Roles and policies (SSO) that are necessary to access the new account. 5. The base networking resources ready to host your compute services. +6. The VPC peerings between the new account and shared + + +## Next steps +Now you have a new account created, so what else? + +To keep creating infra on top of this **binbash Leverage Landing Zone** with this new account added, please check: + +- [X] :books: Check common use cases in [Playbooks](/user-guide/playbooks/) +- [X] :books: Review the [binbash Leverage architecture](/user-guide/ref-architecture-aws/overview/#overview) +- [X] :books: Go for [EKS](/user-guide/ref-architecture-eks/overview/#overview)! diff --git a/docs/try-leverage/aws-account-setup.md b/docs/try-leverage/aws-account-setup.md index 4573fa52..8504e21e 100644 --- a/docs/try-leverage/aws-account-setup.md +++ b/docs/try-leverage/aws-account-setup.md @@ -1,7 +1,7 @@ # Creating your AWS Management account ## Create the first AWS account -First and foremost you'll need to [create an AWS account](/user-guide/ref-architecture-aws/features/organization/configuration/) for your project. This will be the management account of your [AWS Organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html) and the email address you use for signing up will be the [root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) of this account -- you can see this user represented in the [architecture diagram](../#leverage-landing-zone). +First and foremost you'll need to [create an AWS account](/user-guide/ref-architecture-aws/features/organization/configuration/) for your project (note your management account should be called `-management`). This will be the management account of your [AWS Organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html) and the email address you use for signing up will be the [root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) of this account -- you can see this user represented in the [architecture diagram](../#leverage-landing-zone). Since the root user is the main access point to your account it is strongly recommended that you keep its credentials (email, password) safe by following [AWS best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html). @@ -13,7 +13,7 @@ Since the root user is the main access point to your account it is strongly reco ## Create a bootstrap user with temporary administrator permissions Leverage needs a user with temporary administrator permissions in order to deploy the initial resources that will form the foundations you will then use to keep building on. That initial deployment is called the bootstrap process and thus the user required for that is called "the bootstrap user". -To create that user, navigate to the [IAM page](https://console.aws.amazon.com/iam/) and create a user named `mgmt-org-admin` [following step 2 of this leverage doc](/user-guide/ref-architecture-aws/features/organization/configuration/#reference-aws-organization-init-workflow). +To create that user, navigate to the [IAM page](https://console.aws.amazon.com/iam/) and create a user named `mgmt-org-admin` [following steps 2 and 3 of this leverage doc](/user-guide/ref-architecture-aws/features/organization/configuration/#reference-aws-organization-init-workflow). !!! info Bear in mind that the page for creating users may change from time to time but the key settings for configuring the bootstrap user are the following: @@ -36,6 +36,9 @@ Make a note of all of these and keep them in a safe place as you will need them in Binbash's team, then please share that using a secure way (e.g. password management service, GPG keys, etc). +!!! info + If user was set up with the option "Force to change password on first login", you should log into the console to do so. + ## Next steps You have successfully created and configured the AWS account for your Leverage project. From now on, almost all interactions with the AWS environment (with few notable exceptions) will be performed via Leverage. diff --git a/docs/try-leverage/enabling-sso.md b/docs/try-leverage/enabling-sso.md new file mode 100644 index 00000000..ec328159 --- /dev/null +++ b/docs/try-leverage/enabling-sso.md @@ -0,0 +1,102 @@ +# Configure SSO settings + +## Enable SSO +Let's start by configuring SSO settings. Open this file: `/config/common.tfvars` and update the following lines: +``` +sso_enabled = false +sso_start_url = "https://bbleverage.awsapps.com/start" +``` + +Change `sso_enabled` to `true` as follows to enable SSO support: +``` +sso_enabled = true +``` + +Now you need to set the `sso_start_url` with the right URL. To find that, navigate here: `https://us-east-1.console.aws.amazon.com/singlesignon/home` -- you should be already logged in to the Management account for this to work. You should see a "Settings summary" panel on the right of the screen that shows the "AWS access portal URL". Copy that and use it to replace the value in the `sso_start_url` entry. Below is an example just for reference: +``` +sso_start_url = "https://d-xyz01234567.awsapps.com/start" +``` + +!!! tip "Customize the AWS access portal URL" + The 'AWS access portal URL' can be customized to use a more friendly name. Check the [official documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtochangeURL.html) for that. + + +!!! info "Further info on configuring SSO" + There is more information on how to configure SSO [here](/user-guide/ref-architecture-aws/features/sso/configuration/#preparing-the-project-to-use-aws-sso). + +## Update backend profiles in the management account +It's time to set the right profile names in the backend configuration files. Open this file: `management/config/backend.tfvars` and change the `profile` value from this: +``` +profile = "me-bootstrap" +``` +To this: +``` +profile = "me-management-oaar" +``` +Please note that in the examples above my short project name is `me` which is used as a prefix and it's the part that doesn't get replaced. + +## Activate your SSO user and set up your password +The SSO users you created when you provisioned the SSO layer need to go through an email activation procedure. + +The user is the one you set in the `project.yaml` file at the beginning, in this snippet: + +```yaml +users: +- first_name: the-name + last_name: the-last-name + email: user@domain.co + groups: + - administrators + - devops +``` + +To activate the user find the [instructions here](/user-guide/ref-architecture-aws/features/sso/managing-users/#trigger-user-email-activation). + +Once SSO user's have been activated, they will need to get their initial password so they are able to log in. Check out the [steps for that here](/user-guide/ref-architecture-aws/features/sso/managing-users/#reset-a-user-password). + +Basically: + +- Log into your `sso_start_url` address +- Ingress your username (the user email) +- Under Password, choose Forgot password. +- Type in the code shown in the screen +- A reset password email will be sent +- Follow the link and reset your password +- Now, in the same URL as before, log in with the new credentials +- You will be prompted to create an MFA, just do it. + +## Configure the CLI for SSO +Almost there. Let's try the SSO integration now. + +### Configure your SSO profiles +Since this is your first time using that you will need to configure it by running this: + +```bash +leverage aws configure sso +``` + +Follow the wizard to get your AWS config file created for you. There is [more info about that here](/user-guide/ref-architecture-aws/features/sso/configuration/#authentication-via-sso). + +### Verify on a layer in the management account +To ensure that worked, let's run a few commands to verify: + +1. We'll use `sso` for the purpose of this example +2. Move to the `management/global/sso` layer +3. Run: `leverage tf plan` +4. You should get this error: "Error: error configuring S3 Backend: no valid credential sources for S3 Backend found." +5. This happens because so far you have been running Terraform with a different AWS profile (the bootstrap one). Luckily the fix is simple, just run this: `leverage tf init -reconfigure`. Terraform should reconfigure the AWS profile in the `.terraform/terraform.tfstate` file. +6. Now try running that `leverage tf plan` command again +7. This time it should succeed, you should see the message: `No changes. Your infrastructure matches the configuration.` + +**Note** if you still have the same error, try clearing credentials with: + +```bash +leverage aws sso logout && leverage aws sso login +``` + + +## Next steps +You successfully enabled SSO. + +Next, you will orchestrate the remaining accounts, `security` and `shared`. + diff --git a/docs/try-leverage/leverage-project-setup.md b/docs/try-leverage/leverage-project-setup.md index a19705a1..2b3dd6ac 100644 --- a/docs/try-leverage/leverage-project-setup.md +++ b/docs/try-leverage/leverage-project-setup.md @@ -43,6 +43,8 @@ secondary_region: us-west-2 ``` !!! info "The `project_name` field only accepts lowercase alphanumeric characters and allows hyphens('-'). For instance, valid names could be 'example' or 'leveragedemo' or 'example-demo' " +!!! info "The `short_name` field only accepts 2 to 4 lowercase alpha characters. For instance, valid names could be 'exam or 'leve or 'ex " + !!! info "We typically use as 1ry `us-east-1` and 2ry `us-west-2` as our default regions for the majority of our projects. However, please note that these regions may not be the most fitting choice for your specific use case. For detailed guidance, we recommend following these provided [guidelines](https://binbash.atlassian.net/wiki/external/2159050753/NGZkZWMzMTA5M2UwNDQ0OTk3MjUwMGY5NjA0YzRjNjk)." Another example is below. Note that the `management`, `security`, and `shared` accounts have been updated with slightly different email addresses (actually `aws+security@example.com` and `aws+shared@example.com` are email aliases of `aws@example.com` which is a convenient trick in some cases): @@ -77,6 +79,8 @@ users: ... ``` +!!! info "Note these users will be the ones used later for SSO access." + !!! info "The project definition file includes other entries but the ones shown above are the most frequently updated." ## Configure "bootstrap" credentials diff --git a/docs/try-leverage/management-account.md b/docs/try-leverage/management-account.md index 7e42d00a..35011486 100644 --- a/docs/try-leverage/management-account.md +++ b/docs/try-leverage/management-account.md @@ -113,7 +113,7 @@ $ leverage credentials configure --type BOOTSTRAP --skip-access-keys-setup !!! info "More information on [`credentials configure`](/user-guide/leverage-cli/reference/credentials#configure)" ### SSO layer -Before working on the SSO layer you have to navigate to the [AWS IAM Identity Center page](https://console.aws.amazon.com/singlesignon/) and enable Single Sign-On (SSO) by clicking on the `Enable` button. Additionally, to ensure a correct integration, make sure to set the primary region for SSO in AWS console to match the primary region of your Leverage project. e.g. `us-east-1` for both of them. +Before working on the SSO layer you have to navigate to the [AWS IAM Identity Center page](https://console.aws.amazon.com/singlesignon/), set the region to the primary region you've chosen and enable Single Sign-On (SSO) by clicking on the `Enable` button. Now back to the terminal. The SSO layer is deployed in two steps. First, switch to the `global/sso` directory and run the following: ``` bash @@ -141,4 +141,4 @@ leverage terraform apply ## Next steps You have successfully orchestrated the `management` account for your project and configured the credentials for the next steps. -Next, you will orchestrate the remaining accounts, `security` and `shared`. +Now, let's enable SSO for the rest of the process. diff --git a/docs/try-leverage/post-deployment.md b/docs/try-leverage/post-deployment.md index d44e110a..a4b49676 100644 --- a/docs/try-leverage/post-deployment.md +++ b/docs/try-leverage/post-deployment.md @@ -1,106 +1,23 @@ # Post-deployment steps -At this point the landing zone should be almost ready but there are still a few things that need to be changed. For instance, for the sake of simplicity you have been using the bootstrap user for every command. In this section you will make the necessary adjustments to start using your own user. +At this point the landing zone should be ready. -## Configure SSO settings +The bootstrap user can now be deleted. -### Enable SSO -Let's start by configuring SSO settings. Open this file: `config/common.tfvars` and update the following lines: -``` -sso_enabled = false -sso_start_url = "https://bbleverage.awsapps.com/start" -``` +## Delete the bootstrap user -Change `sso_enabled` to `true` as follows to enable SSO support: -``` -sso_enabled = true -``` +- Log into your `sso_start_url` address with your SSO user +- Select the `management` account and log into the `Management console` +- Go to IAM +- Delete the user `mgmt-org-admin` -Now you need to set the `sso_start_url` with the right URL. To find that, navigate here: `https://us-east-1.console.aws.amazon.com/singlesignon/home` -- you should be already logged in to the Management account for this to work. You should see a "Settings summary" panel on the right of the screen that shows the "AWS access portal URL". Copy that and use it to replace the value in the `sso_start_url` entry. Below is an example just for reference: -``` -sso_start_url = "https://d-xyz01234567.awsapps.com/start" -``` +## Adding SSO users and groups -!!! tip "Customize the AWS access portal URL" - The 'AWS access portal URL' can be customized to use a more friendly name. Check the [official documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtochangeURL.html) for that. - - -!!! info "Further info on configuring SSO" - There is more information on how to configure SSO [here](/user-guide/ref-architecture-aws/features/sso/configuration/#preparing-the-project-to-use-aws-sso). - -### Update backend profiles in the management account -It's time to set the right profile names in the backend configuration files. Open this file: `management/config/backend.tfvars` and change the `profile` value from this: -``` -profile = "me-bootstrap" -``` -To this: -``` -profile = "me-management-oaar" -``` -Please note that in the examples above my short project name is `me` which is used as a prefix and it's the part that doesn't get replaced. - -### Update the backend profile in the security directory -One more files to update. Open `security/config/backend.tfvars` and modify the `profile` value from this: -``` -profile = "me-security-oaar" -``` -To this: -``` -profile = "me-security-devops" -``` -Note that in the examples above I only replaced `oaar` for `devops`. - -### Update the backend profile in the shared directory -Now open `shared/config/backend.tfvars` and make the same update. For instance, your `profile` value should change from this: -``` -profile = "me-shared-oaar" -``` -To this: -``` -profile = "me-shared-devops" -``` - -## Activate your SSO user and set up your password -The SSO users you created when you provisioned the SSO layer need to go through an email activation procedure. Find the [instructions here](/user-guide/ref-architecture-aws/features/sso/managing-users/#trigger-user-email-activation). - -Once SSO user's have been activated, they will need to get their initial password so they are able to log in. Check out the [steps for that here](/user-guide/ref-architecture-aws/features/sso/managing-users/#reset-a-user-password). - -## Configure the CLI for SSO -Almost there. Let's try the SSO integration now. - -### Configure your SSO profiles -Since this is your first time using that you will need to configure it by running this: `leverage aws configure sso` - -Follow the wizard to get your AWS config file created for you. There is [more info about that here](/user-guide/ref-architecture-aws/features/sso/configuration/#authentication-via-sso). - -### Verify on a layer in the management account -To ensure that worked, let's run a few commands to verify: - -1. We'll use `base-identities` for the purpose of this example -2. Move to the `management/global/base-identities` layer -3. Run: `leverage tf plan` -4. You should get this error: "Error: error configuring S3 Backend: no valid credential sources for S3 Backend found." -5. This happens because so far you have been running Terraform with a different AWS profile (the bootstrap one). Luckily the fix is simple, just run this: `leverage tf init -reconfigure`. Terraform should reconfigure the AWS profile in the `.terraform/terraform.tfstate` file. -6. Now try running that `leverage tf plan` command again -7. This time it should succeed. -8. Unfortunately, since through this guide we have deployed all the layers with the bootstrap profile you will face the same issue on every layer and thus you will have to repeat steps 5 and 6 to fix it. - -### Verify on a layer in a non-management account -The previous steps provided you with the knowledge to move on with the rest of layers but, just to be sure, let's try on a layer of a non-management account: - -1. Switch to the `security/global/base-identities` directory -2. Run: `leverage tf init -reconfigure` -3. And then run: `leverage tf plan` -4. If that works, that should validate your credentials have been configured successfully. - -That's it! You are ready to roll on your own now! :raised_hand: - -!!! note - If a layer was already set with BOOTSTRAP credentials, when changing the credential type Terraform has to be reconfigured: `leverage tf init -reconfigure`. +To add users or groups, please see [SSO Managing Users document](/user-guide/ref-architecture-aws/features/sso/managing-users). ## Next steps Now you not only have a fully functional landing zone configuration deployed, but also are able to interact with it using your own AWS SSO credentials. -For more detailed information, visit the links below. +For more detailed information on the **binbash Leverage Landing Zone**, visit the links below. - [X] :books: [How it works](/user-guide/ref-architecture-aws/overview/) - [X] :books: [User guide](/user-guide/) diff --git a/docs/try-leverage/security-and-shared-accounts.md b/docs/try-leverage/security-and-shared-accounts.md index 5c435508..11fb1923 100644 --- a/docs/try-leverage/security-and-shared-accounts.md +++ b/docs/try-leverage/security-and-shared-accounts.md @@ -16,6 +16,16 @@ First, go to the `security` directory. cd security ``` +### Set profile + +Since we are using SSO, check in `security/config/backend.tfvars` file the `profile` is set to: + +```yaml +profile = "me-security-devops" +``` + +If it is not, please modify it. Note we are using a sample short project name `me`, use the one you have set. + ### Terraform backend layer Move into the `us-east-1/base-tf-backend` directory and run: ``` bash @@ -57,6 +67,17 @@ Place yourself in the `shared` directory. cd shared ``` +### Set profile + +Since we are using SSO, check in `shared/config/backend.tfvars` file the `profile` is set to: + +```yaml +profile = "me-shared-devops" +``` + +If it is not, please modify it. Note we are using a sample short project name `me`, use the one you have set. + + ### Terraform backend layer Move into the `us-east-1/base-tf-backend` directory and run: ``` bash @@ -96,6 +117,6 @@ leverage terraform apply ``` ## Next steps -You have now a fully deployed landing zone configuration for the Leverage Reference Architecture for AWS, with its three accounts `management`, `security` and `shared` ready to be used. +You have now a fully deployed landing zone configuration for the Leverage Reference Architecture for AWS, with its three accounts management, security and shared ready to be used. -Next, you are going to tackle de last steps configuring the credentials for a user to interact with your Leverage project securely. +Next, you are going to tackle de last steps. diff --git a/docs/user-guide/playbooks/VPC-subnet-calculator.md b/docs/user-guide/playbooks/VPC-subnet-calculator.md new file mode 100644 index 00000000..9feaacac --- /dev/null +++ b/docs/user-guide/playbooks/VPC-subnet-calculator.md @@ -0,0 +1,40 @@ +# How to calculate the VPC subnet CIDRs? + +To calculate subnets [this calculator](https://www.davidc.net/sites/default/subnets/subnets.html?network=172.18.0.0&mask=20&division=15.7231) can be used + +Note in this link a few params were added: the base network and mask, and the division number. In this case the example is for the `shared` account networking. + +This table will be shown: +![subnet-cidr-calculator](/assets/images/screenshots/subnet-cidr-calculator.png "Subnet CIDR calculator"){: style="width:950px"} + +Note how this information is set in the tf file: + +```yaml + vpc_cidr_block = "172.18.0.0/20" + azs = [ + "${var.region}a", + "${var.region}b" + ] + + private_subnets_cidr = ["172.18.0.0/21"] + private_subnets = [ + "172.18.0.0/23", + "172.18.2.0/23" + ] + + public_subnets_cidr = ["172.18.8.0/21"] + public_subnets = [ + "172.18.8.0/23", + "172.18.10.0/23" + ] +``` + +Note the main CIDR is being used for the VPC. See on the left how the `/20` encompasses all the rows. + +Then two divisions for `/21`. Note the first subnet address of the first row for each one is being used for `private_subnets_cidr` and `public_subnets_cidr`. + +Finally the `/23` are being used for each subnet. + +Note we are using the first two subnet addresses for each `/21`. This is due to we are reserving the other two to allow adding more AZs in the future. (up to two in this case) + +If you want you can take as a reference [this page](http://localhost:8000/user-guide/ref-architecture-aws/features/network/vpc-addressing/) to select CIDRs for each account. diff --git a/docs/user-guide/playbooks/VPN-with-no-LandingZone.md b/docs/user-guide/playbooks/VPC-with-no-LandingZone.md similarity index 99% rename from docs/user-guide/playbooks/VPN-with-no-LandingZone.md rename to docs/user-guide/playbooks/VPC-with-no-LandingZone.md index 03ad45ae..cbfe5ad9 100644 --- a/docs/user-guide/playbooks/VPN-with-no-LandingZone.md +++ b/docs/user-guide/playbooks/VPC-with-no-LandingZone.md @@ -1,4 +1,4 @@ -# VPN with no Landing Zone +# VPC with no Landing Zone ## What diff --git a/docs/user-guide/playbooks/index.md b/docs/user-guide/playbooks/index.md index 54648992..9789a665 100644 --- a/docs/user-guide/playbooks/index.md +++ b/docs/user-guide/playbooks/index.md @@ -1,5 +1,6 @@ # Playbooks -- [x] [VPN with no Landing Zone](./VPN-with-no-LandingZone.md) -- [x] [Start/Stop EC2/RDS instances using schedule or manual endpoint](schedule-start-stop-ec2.md) +- [x] [VPC with no Landing Zone](./VPC-with-no-LandingZone.md) +- [x] [Start/Stop EC2/RDS instances using schedule or manual endpoint](./schedule-start-stop-ec2.md) +- [x] [Calculate VPC subnet CIDRs](./VPC-subnet-calculator.md) diff --git a/docs/user-guide/ref-architecture-aws/features/organization/configuration.md b/docs/user-guide/ref-architecture-aws/features/organization/configuration.md index 51e228ce..472ac5c9 100644 --- a/docs/user-guide/ref-architecture-aws/features/organization/configuration.md +++ b/docs/user-guide/ref-architecture-aws/features/organization/configuration.md @@ -45,9 +45,9 @@ the aliases automatically implicitly when running Terraform's Leverage code. - Activate IAM User and Role Access to Billing Information - If needed Update Alternate Contacts - 2. Via AWS Web Console: in `project_name-management` previously created account (eg, name: `leverage-management`, + 2. Via [AWS Web Console](https://us-east-1.console.aws.amazon.com/iam/home#/users): in `project_name-management` previously created account (eg, name: `leverage-management`, email: `aws@binbash.com.ar`) [create the `mgmt-org-admin` IAM user with Admin privileges](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) - (admin IAM policy attached), which will be use for the initial AWS Org bootstrapping. + (attach the `AdministratorAccess` IAM managed policy and enable Web Console and programmatic access), which will be use for the initial AWS Org bootstrapping. - :ledger: **NOTE:** After it’s 1st execution only nominated Org admin users will persist in the `project-management` account. 3. Via AWS Web Console: in `project-management` account create `mgmt-org-admin` IAM user AWS ACCESS KEYS diff --git a/docs/user-guide/ref-architecture-aws/features/sso/managing-users.md b/docs/user-guide/ref-architecture-aws/features/sso/managing-users.md index a01d4c44..9ba7a4a1 100644 --- a/docs/user-guide/ref-architecture-aws/features/sso/managing-users.md +++ b/docs/user-guide/ref-architecture-aws/features/sso/managing-users.md @@ -29,8 +29,8 @@ 3. Go to the users section 4. Locate the user whose email you want to active 5. Click on the user to view the user details -6. There should be a "Send verification email" button at the top. Click on it. +6. There should be a "Send verification email" or "Send email verification link" button at the top. Click on it. 7. Notify the user, confirm that he/she got the email and that he/she clicked on the activation link. ## Reset a user password -Follow the steps in the [official documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/resetuserpwd.html) +Follow the steps in the [official documentation](https://docs.aws.amazon.com/singlesignon/latest/userguide/resetpassword-accessportal.html) diff --git a/docs/work-with-us/releases/versions-compatibility-matrix.md b/docs/work-with-us/releases/versions-compatibility-matrix.md index f9a8ce0c..d1852af5 100644 --- a/docs/work-with-us/releases/versions-compatibility-matrix.md +++ b/docs/work-with-us/releases/versions-compatibility-matrix.md @@ -11,40 +11,9 @@ component by component based on the below presented compatibility matrix table. ## Compatibility Matrix - - - - - - +If you need to know which Leverage CLI versions are compatible with which Leverage Toolbox Docker Images please refer to the [Release Notes](https://github.com/binbashar/leverage/releases). Just look for the section called "Version Compatibility". Bear in mind though that, at the moment, we do not include a full compatibility table there but at least you should be able to find out what's the Toolbox Image that was used for a given release. - - - - - - - - - - - - - - - - - - - - - - - -
Leverage Ref Arch versionLeverage CLILeverage Toolbox
image
version
v1.12.0v1.9.x`binbash/leverage-toolbox`
==1.3.5-0.0.2
`binbash/leverage-toolbox`
==1.2.7-0.1.1
v1.8.x`binbash/leverage-toolbox`
==1.2.7-0.0.x
v1.8.1v1.7.2`binbash/terraform-awscli-slim`
>=1.1.9
v1.7.2v1.6.2`binbash/terraform-awscli-slim`
>=1.1.3
- -Releases which are ~~crossed out~~ _should_ work, but are unlikely to get security or other fixes. -We suggest they should be upgraded soon. +If you are looking for the versions of the software included in the Toolbox Docker Image then go instead to [the release notes of that repo](https://github.com/binbashar/le-docker-leverage-toolbox/releases) instead. ## Release Schedule diff --git a/mkdocs.yml b/mkdocs.yml index 52d8b79b..070c3087 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -164,6 +164,7 @@ nav: - Install Leverage CLI: "try-leverage/local-setup.md" - Create a Leverage project: "try-leverage/leverage-project-setup.md" - Configure the Management account: "try-leverage/management-account.md" + - Enable SSO: "try-leverage/enabling-sso.md" - Configure the Security and Shared accounts: "try-leverage/security-and-shared-accounts.md" - Post-deployment: "try-leverage/post-deployment.md" - Add more AWS Accounts: "try-leverage/add-aws-accounts.md" @@ -289,8 +290,9 @@ nav: - Credentials: "user-guide/troubleshooting/credentials.md" - Playbooks: - Overview: "user-guide/playbooks/index.md" - - VPN with no LandingZone: "user-guide/playbooks/VPN-with-no-LandingZone.md" + - VPC with no LandingZone: "user-guide/playbooks/VPC-with-no-LandingZone.md" - Start/Stop EC2/RDS instances using schedule or manual endpoint: "user-guide/playbooks/schedule-start-stop-ec2.md" + - Calculate VPC cubnet CIDRs: "user-guide/playbooks/VPC-subnet-calculator.md" - Work with us: - Overview: "work-with-us/index.md" - Support: "work-with-us/support.md"