diff --git a/README.md b/README.md index f23a4cd..e8179fb 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,15 @@ -# AWS Access Module +# Terraform AWS Access -This is Alpha; a work in progress, please wait until a version 1 is released to use. +WARNING! This is a work in progress and not ready to be used. -This module provides the basic necessities for connecting to EC2 servers. +This is an "Independent" module, please see [terraform.md](./terraform.md) for more information. -This is a "Core Module", it shouldn't contain any nested "independent modules". Please see [terraform.md](./terraform.md) for more information. - -## Requirements - -### AWS Access +## AWS Access The first step to using the AWS modules is having an AWS account, [here](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html) is a document describing this process. You will need an API access key id and API secret key, you can get the API keys [following this tutorial](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey). - The Terraform AWS provider uses the AWS Go SDK, which allows the use of either environment variables or config files for authentication. https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-settings - You do not need the AWS cli to generate the files, just place them in the proper place and Terraform will find and read them. We use environment variables to configure the AWS provider and load them by sourcing an RC file. @@ -28,26 +22,37 @@ export AWS_REGION='us-west-1' These help the tests set you as the owner on the testing infra and generate the proper key. The `.envrc` file sources `.rcs` file which assumes a local file at path `~/.config/aws/default/rc` exists with the above information. -## Nix +## Examples -These modules use Nix the OS agnostic package manager to install and manage local package dependencies, - install Nix and source the .envrc to enter the environment. -The .envrc will load a Nix development environment (a Nix shell), using the flake.nix file. -You can easily add or remove dependencies by updating that file, the flake.lock is a lock file to cache dependencies. -After loading the Nix shell, Nix will source the .envrc, setting all of the environment variables as necessary. -Nix is an optional way to quickly use the same environment that we use to develop and test, - you can also download and install the dependencies on your local machine. +### Local State -## Local State - -The specific use case for the exaple mmodules here is temporary infrastructure for testing purposes. -With that in mind it is not expected that the user will manage the resources as a team, - therefore the state files are all stored locally. +The specific use case for the example modules is temporary infrastructure for testing purposes. +With that in mind, it is not expected that we manage the resources as a team, therefore the state files are all stored locally. If you would like to store the state files remotely, add a terraform backend file (`*.name.tfbackend`) to your implementation module. https://www.terraform.io/language/settings/backends/configuration#file -## Override Tests +## Development and Testing + +### Paradigms and Expectations + +Please make sure to read [terraform.md](./terraform.md) to understand the paradigms and expectations that this module has for development. + +### Environment + +It is important to us that all collaborators have the ability to develop in similar environments, so we use tools which enable this as much as possible. +These tools are not necessary, but they can make it much simpler to collaborate. + +* I use [nix](https://nixos.org/) that I have installed using [their recommended script](https://nixos.org/download.html#nix-install-macos) +* I use [direnv](https://direnv.net/) that I have installed using brew. +* I simply use `direnv allow` to enter the environment +* I navigate to the `tests` directory and run `go test -v -timeout=5m -parallel=10` +* To run an individual test I nvaigate to the `tests` directory and run `go test -v -timeout=5m -run ` + * eg. `go test -v -timeout=5m -run TestBasic` +* I use `override.tf` files to change the values of `examples` to personalized data so that I can run them + +Our continuous integration tests in the GitHub [ubuntu-latest runner](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md), which has many different things installed. + +### Override Tests You may want to test this code with slightly different parameters for your environment. Check out [Terraform override files](https://developer.hashicorp.com/terraform/language/files/override) as a clean way to modify the inputs without accidentally committing any personalized code. -Our `.gitignore` should prevent committing any `override.tf` that you create. diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 9a53022..0000000 --- a/examples/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Examples - -These are example implementations of this module. -These modules use relative path sourcing so that they can be easily tested by the automation in this repo. -When users implement these modules, please use the Terraform registry. -Set the source attribute equal to the group and name of the module, and the version to the version you would like to use. - -## Basic - -This generates all possible objects, this is a basic Terraform run without exclusions. - -## Override - -This generates no objects, this is a full override of the module. - -## Personal - -This generates only "personal" objects, skipping the creation of a VPC and a subnet. - -## Project - -This generates only "project" objects, generating a subnet and matching security group, but skipping everything else. diff --git a/outputs.tf b/outputs.tf index 12bbe1b..c1d16fe 100644 --- a/outputs.tf +++ b/outputs.tf @@ -1,23 +1,41 @@ output "vpc" { - value = module.vpc.vpc + value = module.vpc.vpc + description = <<-EOT + The VPC object from AWS. + EOT } output "subnet" { - value = module.subnet.subnet + value = module.subnet.subnet + description = <<-EOT + The subnet object from AWS. + EOT } output "cidr" { - value = module.subnet.cidr + value = module.subnet.cidr + description = <<-EOT + The CIDR block of the subnet. + EOT } output "security_group" { - value = module.security_group.security_group + value = module.security_group.security_group + description = <<-EOT + The security group object from AWS. + EOT } output "security_group_name" { - value = module.security_group.name + value = module.security_group.name + description = <<-EOT + The name of the security group. + EOT } output "ssh_key" { - value = module.ssh_key.ssh_key + value = module.ssh_key.ssh_key + description = <<-EOT + The SSH key object from AWS. + EOT }