# hello-world

This example is an introduction to building AWS infrastructure with the CDK. The code
defines an S3 bucket and specifies that a file should be uploaded into the bucket.

Currently, this example is only available in the Go programming language. The sample
will soon be updated to include support for additional languages.

**NOTICE**: Go support is still in Developer Preview. This implies that APIs may
change while the CDK team addresses early feedback from the community.

## Initial Setup

The base code in this example was generated by executing the following commands:

```
mkdir hello-world
cd hello-world
cdk init app --language go
```

**Note:** The directory name is used to generate some of the file names, so when
using the `init` command, be sure to use a name appropriate for your particular situation.

**Note:** To use a language other than Go, substitute your language of choice as follows:
`cdk init app --language typescript`


## Annotations in the code

The language-specific code contains a number of comments which illustrate the
changes added to support creating a bucket and uploading a file. Please refer
to those comments for further details.

## Running the code

To test the code, the following command should be executed:

```
cdk synth
```

Upon a successful invocation, a new directory will be created. The name
of the directory will be `cdk.out`.

## Review the output (cdk.out)

There are a number of files which appear in the `cdk.out` directory:
 - `cdk.out`
 - `HelloWorldStack.template.json`
 - `manifest.json`
 - `tree.json`
 - `asset.{a unique identifier}.zip`

There are also a number of subdirectories - each of which has the following
naming format: `asset.{a unique identifier}`. Each directory corresponds to an
asset that will be uploaded as part of the CloudFormation deployment.

Although the code only specified a single file for upload to the S3 bucket,
there are actually two additional assets of interest:

 1. A zip file which contains the AWS CLI. The file is roughly 11 MB in size
    and resides in the root of the `cdk.out` directory.
 2. A subdirectory which contains a single file named `index.py`. This file is
    used by the CDK / CloudFormation to transfer files to the S3 bucket.


## Deploy the resources

When deploying resources, it's necessary to do three things:

1. Configure account credentials
2. Bootstrap the account
3. Deploy the CDK / CloudFormation resources

### Configure account credentials

The simplest way to configure account credentials is by logging in via the AWS CLI.
There are a number of ways to do this, but the simplest is via `aws configure`.

Once logged in, credentials should be made available via environment variables.
Furthermore, the profile created should be set via the environment variable `$AWS_PROFILE`

For additional information about configuring credentials with the AWS CLI, please
refer to the following article:
https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html

### Bootstrap the account

If this is the first time the CDK is used for a particular account, it's necessary
to bootstrap the account. This is done by running the following command:

`cdk bootstrap`

This command creates an initial set of resources within the target AWS account, and
ensures that deployments will have the necessary access.

Running
`aws cloudformation list-stacks`
should provide output similar to the following:

```
{
    "StackSummaries": [
        {
            "StackId": "<Stack ARN Removed>",
            "StackName": "CDKToolkit",
            "TemplateDescription": "The CDK Toolkit Stack. It was created by `cdk bootstrap` and manages resources necessary for managing your Cloud Applications with AWS CDK.",
            "CreationTime": "2021-09-19T21:49:10.942000+00:00",
            "LastUpdatedTime": "2021-09-19T21:49:16.489000+00:00",
            "StackStatus": "CREATE_COMPLETE",
            "DriftInformation": {
                "StackDriftStatus": "NOT_CHECKED"
            }
        }
    ]
}
```

In addition, navigating in the AWS Console to CloudFormation should show the same stack.
From within the stack, there should be two resources:
 - StagingBucket: An S3 bucket used for staging purposes
 - StagingBucketPolicy: An IAM policy to allow access to the StagingBucket

### Deploy the CDK / CloudFormation resources

To deploy the resources described in the Go code, execute the following command:

`cdk deploy --profile $AWS_PROFILE`

**NOTE:** If you haven't defined an environment variable for the profile, you can explicitly
state the name of it instead of using an environment variable.

This command will upload the defined resources, and start the deployment process.
The progress of the deployment is available via CloudFormation commands. For example,
the following command will provide status information regarding all stacks in
the current account and region:

`aws cloudformation list-stacks`

When the deployment is complete, the CloudFormation status will be `CREATE_COMPLETE`.
At that time, it's possible to verify the success of the deployment by listing the
contents of the S3 bucket:

`aws s3 ls my-happy-bucket-name`

The output should be similar to the following:

```
2021-09-25 16:05:14         12 hello_world.txt
```

Congratulations - the stack has been successfully deployed!

## Destroy the previously deployed resources

It's possible to destroy the previously provisioned and deployed resources by executing
the following command:

`cdk destroy --profile $AWS_PROFILE`

**Note:** By default, this command will not destroy an S3 bucket which contains files.
Therefore, it's necessary to manually delete the S3 bucket.
There is an option to remove the bucket - even if the bucket isn't empty. However, since
this is not a best practice, it's left as an exercise for the reader.



## Additional resources

Additional information about the CDK can be found on the CDK landing page:
https://aws.amazon.com/cdk/