2.0.0 • Published 1 year ago

mancho-school-infrastructure v2.0.0

Weekly downloads
-
License
-
Repository
-
Last release
1 year ago

Welcome to Mancho School Infrastructure project!

Install dependencies

  1. Install Node.js

  2. One of the dependencies @mancho-devs/prorab-infrastructure is in a private Github repository.

    To be able to pull this package, you need to set your own Github personal access token to _authToken in the .npmrc file on the first line.

    Note that once you change this tracked file, it will be marked as modified, which in turn will be included in the upcoming commit. You should NOT commit your access token to the repository. In order to ignore this .npmrc file, run the following command.

    git update-index --skip-worktree .npmrc

  3. Install project dependencies.

    npm i

  4. Install CDK globally.

    npm i -g cdk

Useful commands

  • npm run build compile typescript to js
  • npm run watch watch for changes and compile
  • npm run test perform the jest unit tests
  • cdk deploy deploy this stack to your default AWS account/region
  • cdk diff compare deployed stack with current state
  • cdk synth emits the synthesized CloudFormation template

Create an AWS Account

By default for consistency purpose we create all our resources in Oregon (us-west-2) region.

  1. Create a new Gmail account for infrastruture purpose which will be used for creating a new AWS account. All technical email communications will be held in this email account.
  2. Sign in to the root account.
  3. Visit "My Organizations".
  4. Create a new account.
    1. Specify the new account name.
    2. Specify the newly create email address.
    3. Specify the administrator IAM role name as AdministratorAccess.

  5. Sign in to the new AWS account.

    1. In order to sign in we need to sign out of the root account.
    2. Sign in as an IAM user in the same root account.
    3. Once signed in, choose "Switch Roles" under the account name on the top right menu.
    4. Enter the new account number.
    5. Enter the administrator IAM role name AdministratorAccess.

    Notes: If you need to access the new account with the root email, refer to Accessing a member account as the root user which will explain how to reset the root account password.

  6. Visit the IAM console in the new account.

  7. Create a new IAM administrator user for the newly created AWS account. This will give us access keys and passwords necessary to deploy AWS CDK infrastructure stacks.
  8. Add the new access key and secret pair into the ~/.aws/credentials file on your computer.
  9. Configure the AWS SDK in ~/.aws/config.
    1. Set the region to us-west-2.
    2. Set the format to json.
  10. From now on login using the newly create IAM user of the new account.

Bootstrap the AWS Account and Region

Some infrastructure changes might require staging some files to S3 which is why we need to bootstrap the CDK Toolkit stack with the necessary staging area.

# Mancho School
cdk bootstrap aws://996818757183/us-east-1 --profile mancho-school --app bin/projects/mancho.school/service.js
cdk bootstrap aws://996818757183/us-west-2 --profile mancho-school --app bin/projects/mancho.school/service.js

Populate CDK Context

Some stack need to lookup the default VPC in the account. The VPC information is stored in the cdk.context.json file which we can generate using the following command.

cdk synth --app bin/projects/mancho.school/service.js --profile mancho-school

The above command will populate the VPC values for the Mancho School project. Change the --profile and --app to a different project.

Service Infrastructure Setup

Create CloudFormation Stacks to create resources necessary to setup the service architecture.

The following stacks must be created in this specified order:

  • DomainsStack

    • Resources to manage domains.
    • Creates the root hosted zone.

  • WebsiteStack

    • Resources to create a static Website for production stack.
    • Creates an A record set neccessary for AuthStack.

  • BetaWebsiteStack

    • A copy of WebsiteStack but for beta stack.

  • AuthStack

    • Resources to support authentication.
    • Creates a Cognito user pool neccessary for ServiceAPIStack.

  • StorageStack

    • Storage resources for API.
    • Creates database tables for API.

  • APIStack

    • Lambda function for API.

  • ServiceAPIStack

    • Glue-resources to connect Lambda function with GraphQL server and storage.
npm run test
npm run build

# Mancho School
cdk deploy --profile mancho-school --app bin/projects/mancho.school/dev.js IAMUsersStack
cdk deploy --profile mancho-school --app bin/projects/mancho.school/dev.js IAMStudentsStack

cdk deploy --profile mancho-school --app bin/projects/mancho.school/dev.js IAMStudentsStackTwo

cdk deploy --profile mancho-school --app bin/projects/mancho.school/service.js

Adding a new Student

  1. First, add the user details at the end of the ./lib/projects/mancho-school/students.ts or ./lib/projects/mancho-school/students-two.ts files. The reason we have two or more files is that in CloudFormation a single stack cannot store more than 500 resources. The first students.ts file already has enough students that generate around 500 resources. One day we must create the third, fourth and so on files.
  2. Then, deploy IAMStudentsStack or IAMStudentsStackTwo which will create a new IAM user and send an email to the student with AWS authentication credentials.
  3. Then, deploy ${username}StudentWebsiteStack which will deploy production website for the student. For example, esengineerStudentWebsiteStack. It is required to deploy the production website first because it will create the website subdomain which the beta subdomain will depend on.
  4. Finally, deploy ${username}WebsitePipelineStack which will deploy beta website for the student as well as the website pipeline for both stages. For example, esengineerWebsitePipelineStack.

Removing a Student

  1. Remove its pipeline stack ${username}WebsitePipelineStack.
  2. Empty, then remove the S3 bucket created for the student's pipeline stack.
  3. Remove its website stacks ${username}StudentWebsiteStack
  4. Remove the user from the ./lib/projects/mancho-school/students.ts file.
  5. Deploy the IAMStudentsStack.

DomainsStack

  1. Once you deploy the DomainsStack, visit the Route53 console.
  2. Choose the newly created hosted zone for your root domain.
  3. Note the values of the NS DNS record. Usually there are four nameservers provided.
  4. Visit the Website of your domain's provider.
  5. Navigate to your domain page.
  6. Update the Namespaces fields with the NS DNS record values from the Route53 console.

Wait some time (about 10 minutes) for the Amazon Certificate Manager to validate the domain and create an SSL certificate.

AuthStack

When deploying an AuthStack one must first deploy the production stack followed by the beta stack because the domain name in the beta stack requires an A record of the parent root domain to exist.

When implementing the AuthStack for a project, one needs to decide which sign-in providers are necessary for authentication purpose. Currently the following providers have been implemented:

  • Google

AuthStack in some projects define Lambda based triggers. This means that those AuthStack depend on CFNPipelineStack to be deployed in advance. On the other hand CFNPipelineStack depends on AuthStack. For this reason it is necessary to first disable triggers in AuthStack and deploy it. Then deploy CFNPipelineStack, then enable the triggers in the AuthStack. Finally, redeploy the AuthStack.

Google

  1. Go to the Google Cloud Platform Credentials page.
  2. Click Create credentials > OAuth client ID.
  3. Configure Consent Screen
  4. Fill the OAuth consent screen.
  5. For OAuth consent screen click Add or remove scopes
  6. Choose both userinfo.email and userinfo.profile options. Press Update.
  7. Save and continue.
  8. Add Test users.
  9. Save and continue.
  10. Back to Credentials
  11. Create credentials > OAuth client ID.
  12. Select the Web application application type.
  13. Name your OAuth 2.0 client.
  14. For Authorized JavaScript origins enter the custom authorization domain name like https://auth.<ROOT_DOMAIN> where <ROOT_DOMAIN> should be replaced by the new domain name.
  15. Finally, click Create.
  16. Copy the Client ID and Client Secret.
  17. Paste the values into the props for the providers.

Manual Operations

Amazon Cognito SMS text message deliveries

SMS sandbox

When we start using Amazon SNS to send SMS messages, out AWS account is in the SMS sandbox. Refer to https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox.html for more details.

We can send SMS only to the phone numbers we have manually entered in the Console. Therefore enter them in the Amazon SNS Console https://us-west-2.console.aws.amazon.com/sns/v3/home?region=us-west-2#/mobile/text-messaging.

Moving out of the SMS sandbox

Moving your AWS account out of the SMS sandbox requires that you first add, verify, and test destination phone numbers. Then, you must create a case with AWS Support.

Refere to https://docs.aws.amazon.com/sns/latest/dg/sns-sms-sandbox-moving-to-production.html for isntructions.

SMS Limits

By default AWS sets a hard spend limit of $1 USD which controls the number of text messages (equivalent to 6 SMS messsages) send from one account. We need to request a limit increase in order to lift this number higher.

  1. Open a new support case at https://console.aws.amazon.com/support/home#/case/create
  2. Select "Service limit increase" support case.
  3. For "Limit type" choose "SNS Text Messaging".
  4. For "... type of messages..." choose "Transactional".
  5. For "... AWS Region..." choose "US West (Oregon)".
  6. Fill out other field if necessary.
  7. Once the limit is increased, edit the "Text messaging preferences" in the Amazon SNS Console https://us-west-2.console.aws.amazon.com/sns/v3/home?region=us-west-2#/mobile/text-messaging/edit-preferences.

Usually the limit increase happens rather quickly like several minutes.

TODO

  1. Create Apple application ID for auth.
  2. Create Google application ID for auth.
@mancho-devs/prorab-infrastructureaws-cdkaws-cdk-libconstructslodash.groupbylodash.kebabcasesource-map-support
2.0.0

1 year ago