Improve README and config files

Author: csanquer

.editorconfig

@@ -9,6 +9,7 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
+indent_size = 2
 trim_trailing_whitespace = false
 
 [*.yml]

.gitignore

@@ -3,6 +3,7 @@ terraform.tfvars
 terraform.tfstate
 terraform.tfstate.backup
 /terraform/gitlab/ssh_host_keys.tar.gz
+/tmp_ssh_host_keys
 .terraform/
 .terraform.tfstate.lock.info
 /graphs

Makefile

@@ -3,6 +3,7 @@ SHELL := $(shell which bash)
 ENV = /usr/bin/env
 # default shell options
 .SHELLFLAGS = -c
+SSH_KEY_COMMENT = "root@gitlab"
 format = png
 .SILENT: ; # no need for @
 .ONESHELL: ; # recipes execute in same shell
@@ -20,15 +21,17 @@ all:
 # between SSH load balancer
 ssh_host_keys:
 if [ ! -f terraform/gitlab/ssh_host_keys.tar.gz ]; then \
-echo "generating Gitlab ssh host keys" \
+echo "generating Gitlab ssh host keys";\
 rm -rf tmp_ssh_host_keys ;\
 mkdir -p tmp_ssh_host_keys ;\
 cd tmp_ssh_host_keys ;\
-ssh-keygen -q -t dsa -N "" -f ssh_host_dsa_key -C "root@gitlab" ;\
-ssh-keygen -q -t rsa -N "" -f ssh_host_rsa_key -C "root@gitlab" ;\
-ssh-keygen -q -t ecdsa -N "" -f ssh_host_ecdsa_key -C "root@gitlab" ;\
-ssh-keygen -q -t ed25519 -N "" -f ssh_host_ed25519_key -C "root@gitlab" ;\
+ssh-keygen -q -t dsa -N "" -f ssh_host_dsa_key -C $(SSH_KEY_COMMENT) ;\
+ssh-keygen -q -t rsa -N "" -f ssh_host_rsa_key -C $(SSH_KEY_COMMENT) ;\
+ssh-keygen -q -t ecdsa -N "" -f ssh_host_ecdsa_key -C $(SSH_KEY_COMMENT) ;\
+ssh-keygen -q -t ed25519 -N "" -f ssh_host_ed25519_key -C $(SSH_KEY_COMMENT) ;\
 tar -cvzf ../terraform/gitlab/ssh_host_keys.tar.gz ssh_host_* ;\
+cd .. ;\
+rm -rf tmp_ssh_host_keys ;\
 fi;
 
 config: ssh_host_keys
@@ -79,6 +82,7 @@ graphs: _graph_dir
 make _graph type=validate format=$(format)
 make _graph type=input format=$(format)
 make _graph type=refresh format=$(format)
+echo "Graphs exported to graphs directory"
 
 destroy: _get_modules
 cd terraform

README.md

@@ -18,8 +18,75 @@ Requirements
 ------------
 
 * a [AWS account](https://aws.amazon.com/) (**Be careful this template implies creating billable resources on AWS cloud**)
+
+ You will need an [AWS access key](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) and enough admin permissions to create AWS ressources
 * a [AWS Route 53 DNS zone](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) already created (the template will add new subdomain DNS A records)
 * a SSH Key pair to connect to Gitlab and AWS instances (see [Github help for examples](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/))
 * [Packer](https://www.packer.io/) >= 0.12
 * [Terraform](https://www.terraform.io/) >= 8.2
 * GNU Make or some Unix equivalent Implementation
+* *(optional)* [Graphiz](http://www.graphviz.org/) to generate Terraform config Graph Images 
+ ```sh
+ # on ubuntu/debian
+ sudo apt-get install graphviz
+ ```
+
+
+Usage
+-----
+
+### To create the Gitlab infrastructure
+
+1. Copy and edit the configuration files :
+
+ * **terraform** : `terraform/terraform.dist.tvars` to `terraform/terraform.tvars`
+ * **packer** : `packer/config.dist.json` to `packer/config.json`
+ 
+2. create Amazon Machine Images :
+
+ * Gitlab 
+ * Gitlab-CI-multirunner 
+
+ ```sh
+ make ami
+ ```
+ 
+3. check Terraform plan 
+
+ ```sh
+ make plan
+ ```
+
+3. if terraform plan is correct, create AWS resources by applying the terraform plan
+
+ ```sh
+ make apply
+ ```
+
+ * you can check again the terraform exported variables output
+ ```sh
+ make output
+ ```
+ * you can also get Graphviz graphs of all terraform config
+ ```sh
+ # in PNG image format
+ make graphs
+ # or in SVG
+ make graphs format=svg
+ ```
+
+After creation, wait for a few minutes the autoscaled gitlab instances finish self initialization.
+
+if variables are set in `packer/config.json` like :
+```
+aws_dns_zone = "my-aws.net"
+gitlab_dns_subdomain = "gitlab"
+```
+
+The Gitlab server should be available to http://gitlab.my-aws.net/ 
+
+### To destroy the Gitlab infrastructure 
+
+```sh
+make destroy
+```

terraform/global/dns.tf

@@ -4,7 +4,7 @@ data "aws_route53_zone" "selected" {
 
 resource "aws_route53_record" "bastion1" {
  zone_id = "${data.aws_route53_zone.selected.zone_id}"
- name = "bastion1.${data.aws_route53_zone.selected.name}"
+ name = "${var.bastion_dns_subdomain}.${data.aws_route53_zone.selected.name}"
  type = "A"
  ttl = "300"
  records = ["${aws_eip.bastion1.public_ip}"]

terraform/global/variables.tf

@@ -2,9 +2,9 @@ variable "aws_dns_zone" {
  description = "AWS Route53 zone"
 }
 
-variable "gitlab_dns_subdomain" {
- description = "AWS Route53 zone"
- default = "gitlab"
+variable "bastion_dns_subdomain" {
+ description = "Bastion DNS subdomain"
+ default = "bastion1"
 }
 
 variable "aws_az1" {

terraform/main.tf

@@ -8,7 +8,7 @@ module "global" {
  source = "./global"
 
  aws_dns_zone = "${var.aws_dns_zone}"
- gitlab_dns_subdomain = "${var.gitlab_dns_subdomain}"
+ bastion_dns_subdomain = "${var.bastion_dns_subdomain}"
  aws_az1 = "${var.aws_az1}"
  aws_az2 = "${var.aws_az2}"
  vpc_cidr = "${var.vpc_cidr}"

terraform/terraform.dist.tfvars

@@ -1,22 +1,41 @@
-aws_access_key =
-aws_secret_key =
+// Your Amazon Web Service Access Key http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
+aws_access_key = ""
+// Your Amazon Web Service private secret Key
+aws_secret_key = ""
 
+// The AWS Region where to build
 aws_region = "eu-west-1"
+// 2 different Availability Zone for the previous AWS Region
 aws_az1 = "eu-west-1a"
 aws_az2 = "eu-west-1b"
 
-admin_ssh_public_key =
+// Your SSH public key to connect to AWS EC2 instances e.g. : the content of ~/.ssh/id.rsa.pub
+admin_ssh_public_key = ""
 
+// the IP addresses (CIDR range) to restrict SSH access to the bastions
 sg_ssh_cidr = "0.0.0.0/0"
 
-gitlab_db_password =
-gitlab_root_password =
-gitlab_ci_registration_token =
+// Gitlab Postgresql Database password
+gitlab_db_password = ""
+// Gitlab default root account password
+gitlab_root_password = ""
+// Gitlab default Registration token for Gitlab CI
+gitlab_ci_registration_token = ""
 
-aws_dns_zone =
+// your AWS route 53 Zone Base Domain e.g.: "my-domain.com"
+aws_dns_zone = ""
+// the Gitlab subdomain
 gitlab_dns_subdomain = "gitlab"
+// the Bastion subdomain
+bastion_dns_subdomain = "bastion1"
 
+// Number of Gitlab static instances (not in the autoscaling group)
 gitlab_static_instances = 0
+
+// Gitlab autoscaling
+// Maximum number of Gitlab instances
 gitlab_max = 3
+// Minimum number of Gitlab instances
 gitlab_min = 1
+// Desired number of Gitlab instances
 gitlab_desired = 2

terraform/variables.tf

@@ -11,10 +11,15 @@ variable "aws_dns_zone" {
 }
 
 variable "gitlab_dns_subdomain" {
- description = "AWS Route53 zone"
+ description = "Gitlab DNS subdomain"
  default = "gitlab"
 }
 
+variable "bastion_dns_subdomain" {
+ description = "Bastion DNS subdomain"
+ default = "bastion1"
+}
+
 variable "aws_az1" {
  description = "AWS EC2 availability zone 2"
  default = "eu-west-1a"