Merge pull request #4 from matttrach/add-descriptions
add descriptions to the outputs and update the README
This commit is contained in:
Matt Trachier
GitHub
commit
acadba47f8
55
README.md
55
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 <test function name>`
|
||||
* 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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
30
outputs.tf
30
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
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue