Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs fixing #2

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Docs fixing #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8de99d3
deploy-remote-signer.md
denver-s Jun 21, 2021
4a141ea
Fix docs
denver-s Jun 21, 2021
b582d8b
production-readiness: remove identical namespaces
denver-s Jun 21, 2021
fb53c50
bring-up -> boostrapping
denver-s Jun 21, 2021
74cb5d9
typo
denver-s Jun 21, 2021
049ae56
production-readiness: fix sources versions
denver-s Jun 21, 2021
1105cb7
production-readiness: restore v2.0
denver-s Jun 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions cloud-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Cloud Architecture

The best known baking tool, Kiln, is a complete solution for home baking, to be installed on physical hardware. MIDL.dev, in contrast, outsources most of the computing to the cloud, increasing reliability and decreasing the operating burden of the baking operations.
The best known baking tool, [Kiln](https://gitlab.com/tezos-kiln/kiln/), is a complete solution for home baking, to be installed on physical hardware. MIDL.dev, in contrast, outsources most of the computing to the cloud, increasing reliability and decreasing the operating burden of the baking operations.

## Managed Kubernetes

Expand All @@ -18,7 +18,7 @@ Tezos mainnet is fully supported as well as Carthagenet and future test networks

Network security policies are applied in every pod to ensure all traffic is legitimate.

## Fast bringup time
## Fast bootstrapping

The nodes are brought up from a snapshot for faster turnaround time and disaster recovery.

Expand Down
14 changes: 7 additions & 7 deletions deploy-remote-signer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Deploy a baker with remote signer

The [quickstart]() indicates how to set up a cloud baker with the private keys hosted in a Kubernetes secrets. In this section, we configure a remote signer on-premises. This configuration is more secure and every mainnet deployment should use it.
The [quickstart guide](quickstart) indicates how to set up a cloud baker with the private keys hosted in [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). In this section, we configure a remote signer on-premises. This configuration is more secure and every mainnet deployment should use it.

## Prerequisites

Expand All @@ -12,7 +12,7 @@ First, deploy the Tezos-on-GKE baking setup in the cluster.

You may deploy it from the tezos-on-gke repo itself using the [quickstart](https://github.com/midl-dev/tezos-on-gke) instructions, however it is better to follow [production best practices](production-readiness).

In these instructions, we will be declaring a `tezos-baker` terraform module, keeping all sensitive data in a `terraform.tfvars` file.
In these instructions, we will be declaring a `tezos-baker` Terraform module, keeping all sensitive data in a `terraform.tfvars` file.

First, on an empty project dir, create a new `main.tf` file:

Expand All @@ -37,7 +37,7 @@ Note that `authorized_signers` is empty for now.

### ssh endpoint host key

A ssh server normally generates its host keys during installation. Here, we are generating them externally and injecting them into the setup as a terraform and kubernetes secrets.
A ssh server normally generates its host keys during installation. Here, we are generating them externally and injecting them into the setup as a Terraform and Kubernetes Secrets.

This way, in case of complete destruction of the cluster, the operator is able to restore the ssh endpoint with the same host key.

Expand All @@ -51,7 +51,7 @@ To generate a RSA host key, issue the following command on any computer:
ssh-keygen -q -N "" -t rsa -b 4096 -f tezos_tunnel_endpoint_host_rsa_key
```

This value is sensitive, so we will configure it as a terraform variable. In the terraform module, we are passing it as a variable:
This value is sensitive, so we will configure it as a Terraform variable. In the Terraform module, we are passing it as a variable:

```
signer_target_host_key=var.signer_target_host_key
Expand Down Expand Up @@ -103,7 +103,7 @@ cat /home/tezos/.ssh/id_rsa.pub

### Configure the endpoint

You may now declare this remote signer in the terraform parameter `baking_nodes`.
You may now declare this remote signer in the Terraform parameter `baking_nodes`.

The `authorized_signers` list takes signer maps consisting of the following key/value pairs:

Expand Down Expand Up @@ -131,11 +131,11 @@ module "tezos-baker" {
}
```

Then `taint` and `apply` the terraform module.
Then `taint` and `apply` the Terraform module.

### Test the endpoint

Once terraform has deployed, you should be able to ssh from the signer to the endpoint.
Once Terraform has deployed, you should be able to ssh from the signer to the endpoint.

Test it by sshing to the signer as `tezos` user, then:

Expand Down
53 changes: 26 additions & 27 deletions production-readiness.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,30 @@ Usage of [Google Default Application Credentials](https://cloud.google.com/docs/

Instead:

* ensure that you have set up an Organization - that can be done by registering a domain name and adding it to gcloud
* create a Terraform Admin Project, Terraform Service Account and Service Account Credentials following [this Google guide](https://cloud.google.com/community/tutorials/managing-gcp-projects-with-terraform)
* do not pass `project` as a variable when deploying the resources. Instead, pass `organization_id` and `billing_account` as variables
* pass the service account credentials json file `serviceAccount:terraform@${TF_ADMIN}.iam.gserviceaccount.com` as `terraform_service_account_credentials` terraform variable
* ensure that you have set up an Organization - that can be done by registering a domain name and adding it to Google Cloud;
* create a Terraform Admin Project, Terraform Service Account and Service Account Credentials following [this Google guide](https://cloud.google.com/community/tutorials/managing-gcp-projects-with-terraform);
* do not pass `project` as a variable when deploying the resources. Instead, pass `organization_id` and `billing_account` as variables;
* pass the service account credentials JSON file `serviceAccount:terraform@${TF_ADMIN}.iam.gserviceaccount.com` as `terraform_service_account_credentials` Terraform variable.

That will create the cluster in a new project, created by the terraform service account.
That will create the cluster in a new project, created by the Terraform service account.

You may then grant people in your organization access to the project. It is recommended to write more terraform manifests to do so.
You may then grant people in your organization access to the project. It is recommended to write more Terraform manifests to do so.

## Separate cluster definition from baker definition

While you can create a baker in one-shot, it is best suited for demos and testnets. A production baker is best advised to be defined declaratively.

You would normally write all the parameters defining your baker in a `terraform.tfvars` file in your laptop.
You would normally write all the parameters defining your baker in a `terraform.tfvars` file on your machine.

Instead, it is recommended to create a maintain a private terraform manifest, declaring a cluster, and every deployment that lives within. This way, the paramters defining your cluster can also be committed to git (except secrets which should be handled separately, more on this below).
Instead, it is recommended to create and maintain a private Terraform manifest, declaring a cluster, and every deployment that lives within. This way, the paramters defining your cluster can also be committed to git (except secrets which should be handled separately, more on this below).

This keeps the setup maintainable by letting you define several deployments within the same cluster. For example, you may deploy the Tezos baker setup, and the Tezos monitoring setup, within the same cluster.
This keeps the setup maintainable by letting you define several deployments within the same cluster. For example, you may to deploy the Tezos baker setup, and the Tezos monitoring setup, within the same cluster.

### Define the cluster

The [terraform-gke-blockchain](https://github.com/midl-dev/terraform-gke-blockchain) repository contains boilerplate terraform code to deploy a kubernetes cluster.
The [terraform-gke-blockchain](https://github.com/midl-dev/terraform-gke-blockchain) repository contains boilerplate Terraform code to deploy a Kubernetes cluster.

Start by declaring one empty cluster and one terraform provider:
Start by declaring one empty cluster and one Terraform provider:

```
module "terraform-gke-blockchain" {
Expand All @@ -53,21 +53,21 @@ provider "kubernetes" {
}
```

Notice that we created two node pools. These are distinct virtual machines that run your kubernetes cluster. You can map your pods to either. We will be using these to separate the baker setup from the payout/monitoring setup.
Notice that we created two node pools. These are distinct virtual machines that run your Kubernetes cluster. You can map your pods to either. We will be using these to separate the baker setup from the payout/monitoring setup.

### Define the tezos baker
### Define the Tezos baker

Within the `tezos-on-gke` repository, the `terraform-no-cluster-create` folder will deploy the baker on a pre-existing cluster.

The output parameters of the `terraform-gke-blockchain` module become the input parameters of the Tezos baker module.

All variables will appear in the terraform manifest itself, except secrets. Secrets should be kept as variables, and handled appropriately.
All variables will appear in the Terraform manifest itself, except secrets. Secrets should be kept as variables, and handled appropriately.

It looks like:

```
module "tezos-baker" {
source = "github.com/midl-dev/tezos-on-gke?ref=v2.0//terraform-no-cluster-create"
source = "github.com/midl-dev/tezos-on-gke?ref=v3.0//terraform-no-cluster-create"
region = module.terraform-gke-blockchain.location
node_locations = module.terraform-gke-blockchain.node_locations
kubernetes_endpoint = module.terraform-gke-blockchain.kubernetes_endpoint
Expand Down Expand Up @@ -98,11 +98,11 @@ module "tezos-baker" {

It is recommended to use a remote signer for secure operations.

Below is an example of baker with remote signer configured:
Below is an example of a baker with remote signer configured:

```
module "tezos-baker" {
source = "github.com/midl-dev/tezos-on-gke?ref=v2.0//terraform-no-cluster-create"
source = "github.com/midl-dev/tezos-on-gke?ref=v3.0//terraform-no-cluster-create"
region = module.terraform-gke-blockchain.location
node_locations = module.terraform-gke-blockchain.node_locations
kubernetes_endpoint = module.terraform-gke-blockchain.kubernetes_endpoint
Expand Down Expand Up @@ -135,9 +135,9 @@ module "tezos-baker" {
}
```

### With payout config
### Payout configuration

The `baking_nodes` section also accepts a config for TRD payouts. See the [TRD payouts](trd-payouts) section for details.
The `baking_nodes` section also accepts a config for TRD payouts (see the [TRD payouts](trd-payouts) section for details).

## Terraform remote state

Expand Down Expand Up @@ -177,7 +177,7 @@ terraform {
}

module "terraform-gke-blockchain" {
source = "github.com/midl-dev/terraform-gke-blockchain?ref=v1.0"
source = "github.com/midl-dev/terraform-gke-blockchain?ref=v2.0"
org_id = "<my org id, defined above>"
billing_account = "<my billing account, defined above>"
project_prefix = "mybakingop"
Expand All @@ -188,7 +188,7 @@ module "terraform-gke-blockchain" {
}

module "tezos-baker" {
source = "github.com/midl-dev/tezos-on-gke?ref=v2.0//terraform-no-cluster-create"
source = "github.com/midl-dev/tezos-on-gke?ref=v3.0//terraform-no-cluster-create"
region = module.terraform-gke-blockchain.location
node_locations = module.terraform-gke-blockchain.node_locations
kubernetes_endpoint = module.terraform-gke-blockchain.kubernetes_endpoint
Expand All @@ -201,7 +201,6 @@ module "tezos-baker" {
kubernetes_name_prefix = "xtz"
full_snapshot_url = "https://mainnet.xtz-shots.io/full"
rolling_snapshot_url = "https://mainnet.xtz-shots.io/rolling"
kubernetes_namespace = "tezos"
tezos_version = "v9.2"
tezos_network = "mainnet"
signer_target_host_key=var.signer_target_host_key
Expand Down Expand Up @@ -261,8 +260,8 @@ A production validator should be operated with an on-call rotation, meaning seve

Specifically:

* secrets should be moved from a file in the operator workspace to a production secret store such as [Hashicorp Vault](vaultproject.io)
* terraform deploys should be done by a CI system
* any manual change in the kubernetes environment should be recorded in an audit log and committed in the code:
* the terraform private file above can be applied with continuous integration
* the intermediate kubernetes code generated with kustomize could be stored in a CI pipeline and deployed in an auditable way as well (see [Gitops](https://www.weave.works/technologies/gitops/)).
* secrets should be moved from a file in the operator workspace to a production secret store such as [Hashicorp Vault](vaultproject.io);
* Terraform deploys should be done by a CI system;
* any manual change in the Kubernetes environment should be recorded in an audit log and committed in the code:
* the Terraform private file above can be applied with continuous integration;
* the intermediate Kubernetes code generated with kustomize could be stored in a CI pipeline and deployed in an auditable way as well (see [Gitops](https://www.weave.works/technologies/gitops/)).
Loading