To configure the project, clone this repository and copy either `default-kovan.env` or `default-mainnet.env` file to `.env`.
Review the `SHARED_ENV_PATH` configurations, no changes are required, but depending on the use case, you may need copy these examples to a new directory and make your changes.
!! Update DATA_TRANSPORT_LAYER__L1_RPC_ENDPOINT to a valid endpoint !!
### Settings
Change any other settings required for your environment
| COMPOSE_FILE | The yml files to use with docker-compose | replica.yml:replica-shared.yml
| ETH_NETWORK | Ethereum Layer1 and Layer2 network (mainnet,kovan) | kovan (change to `mainnet` for the production network)
| DATA_TRANSPORT_LAYER__L1_RPC_ENDPOINT | An endpoint for the L1 network, either kovan or mainnet.
| DATA_TRANSPORT_LAYER__L2_RPC_ENDPOINT | Optimistic endpoint, such as https://kovan.optimism.io or https://mainnet.optimism.io
| REPLICA_HEALTHCHECK__ETH_NETWORK_RPC_PROVIDER | The L2 endpoint to check the replica against | (typically the same as the DATA_TRANSPORT_LAYER__L2_RPC_ENDPOINT)
| SEQUENCER_CLIENT_HTTP | The L2 sequencer to forward tx to | (typically the same as the DATA_TRANSPORT_LAYER__L2_RPC_ENDPOINT)
| SHARED_ENV_PATH | Path to a directory containing env files | [a directory under ./kustomize/replica/envs](https://github.com/optimisticben/op-replica/tree/main/kustomize/replica/envs)
| GCMODE | Whether to run l2geth as an `archive` or `full` node | archive
| L2GETH_IMAGE_TAG | L2geth version | 0.5.8 (see below)
| DTL_IMAGE_TAG | Data transport layer version | latest (see below)
| HC_IMAGE_TAG | Health check version | latest (see below)
| L2GETH_HTTP_PORT | Port number for the l2geth RPC endpoint | 9991
| L2GETH_WS_PORT | Port number for the l2geth WebSockets endpoint | 9992
| DTL_PORT | Port number for the DTL endpoint, for troubleshooting | 7878
| GETH_INIT_SCRIPT | The script name to run when initializing l2geth | A file under kustomize/replica/bases/configmaps/
### Docker Image Versions
We recommend using the latest versions of both docker images. Find them as GitHub tags
[here](https://github.com/ethereum-optimism/optimism/tags) and as published Docker images linked in the badges:
| [`@eth-optimism/l2geth`](https://github.com/ethereum-optimism/optimism/tree/master/l2geth) | [](https://hub.docker.com/r/ethereumoptimism/l2geth/tags?page=1&ordering=last_updated) |
| [`@eth-optimism/data-transport-layer`](https://github.com/ethereum-optimism/optimism/tree/master/packages/data-transport-layer) | [](https://hub.docker.com/r/ethereumoptimism/data-transport-layer/tags?page=1&ordering=last_updated) |
| [`@eth-optimism/replica-healthcheck`](https://github.com/ethereum-optimism/optimism/tree/master/packages/replica-healthcheck) | [](https://hub.docker.com/r/ethereumoptimism/replica-healthcheck/tags?page=1&ordering=last_updated) |
## Usage
| Action | Command |
| - | - |
| Start the replica (after which you can access it at `http://localhost:L2GETH_HTTP_PORT` | `docker-compose up -d` |
| Get the logs for `l2geth` | `docker-compose logs -f l2geth-replica` |
| Get the logs for `data-transport-layer` | `docker-compose logs -f data-transport-layer` |
| Stop the replica | `docker-compose down` |
## Sync Check
There is a sync check container. It fails at startup because at that point the replica is not running yet. It exposes metrics on port 3000, which you could pick up with a Prometheus. You can view its status with this command:
```sh
docker-compose logs -f replica-healthcheck
```
## Registration
[Register here](https://groups.google.com/a/optimism.io/g/optimism-announce) to get announcements, such as notifications of when you're supposed to update your replica.
This README covers the features used in the [kovan replica overlay](./overlays/kovan-replica-0-4-3/kustomization.yaml)
The first 2 lines are required to be a valid kustomzation target and describe how the file will be processed.
```
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
```
---
The next line is a global namespace setting. This namespace will apply to, and override, the namespace on **all** generated resources.
This makes it very safe as you know the namespace affected by a deployment! But, can't always be used if you need to deploy to multiple namespaces. In that case the namespace can be applied by a referenced kustomization.
```
namespace:kovan-replica-0-4-3
```
---
Next we list the base resources we want to include in this overlay. Since we don't need all the components, we'll select the relevant directories.
```
resources:
- ../../bases/data-transport-layer
- ../../bases/l2geth-replica
- ../../bases/configmaps
- ../../bases/servicemonitors
- ../../bases/replica-healthcheck
```
In addition to the base resources, we also need to create some specific to this overlay.
```
- ./l2geth-volume.yaml
```
Kustomize will add these overlay resources to the build output.
----
The next feature is a `configMapGenerator`. A generator will collect the data from the files (in this case environmental files) and create a configMap with the contents.
**Generators also apply a hash to the configMap** to track changes! You don't have to worry too much about this as the process is automatic and kustomize updates the resources that reference the configMap with the hashed name.
```
configMapGenerator:
- name: data-transport-layer
envs:
- replica-data-transport-layer.env
- name: l2geth-replica
envs:
- replica-l2geth.env
```
This is nice because the files can stay in their native format and allows CI to check files for validity. For example you can run `shellcheck` on scripts that get included in configMaps.
---
Next are the image replacements. You can simply identify a target image you want to replace, provide a new image name and tag. Anywhere that image is found, it's replaced with the overlay setting.
```
images:
- name: ethereumoptimism/data-transport-layer
newName: ethereumoptimism/data-transport-layer
newTag: 0.4.3
- name: ethereumoptimism/l2geth
newName: ethereumoptimism/l2geth
newTag: 0.4.3
```
---
Now we start patching the resources. If you just want to override something, the `patchesStrategicMerge` feature is pretty simple. In the patch file you define the path to the values you want to replace
(kustomization.yaml)
```
patchesStrategicMerge:
- patch-l2geth-resources.yaml
```
(patch-l2geth-resources.yaml)
```
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: l2geth-replica
spec:
template:
spec:
containers:
- name: l2geth-replica
resources:
limits:
memory: 6Gi
requests:
memory: 6Gi
```
In this way we can easily update keys with brand new settings.
But, this method will not work if you want to add or replace a list item.
In these cases we define a target for the patch and a definition of the modification.
(kustomization.yaml)
```
patches:
- path: patch-l2geth-volumes.yaml
target:
group: apps
version: v1
kind: StatefulSet
name: l2geth-replica
```
(patch-l2geth-volumes.yaml)
```
- op: replace
path: /spec/template/spec/volumes/2
value:
name: l2geth-replica-data
persistentVolumeClaim:
claimName: l2geth-replica-data
```
This patch acts on the StatefuleSet `l2geth-replica` and replaces the 3rd volume with a `persistentVolumeClaim`.
We define the `persistentVolumeClaim` as a local resource in `l2geth-volume.yaml`
[Kustomize](https://kustomize.io/) is a way to build custom kubernetes manifests in a template-free way.
This directory describes how to build and deploy Optimistic Ethereum software to a kubernetes cluster.
## Prerequisits
-`kubectl`**Minimum version v1.20**[Install notes](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-kubectl-on-linux)
- a kubernetes cluster
## Structure
The kustomization starts from a folder in `./bases`. Directories under `bases` should describe components in their most generic form. It is possible to deploy directly from a `bases` directory if no resource modification is needed.
The other folders are "overlays", or configuration that will modify resources defined in `bases`.
## Kustomizing with a new overlay
Kustomize build resources based on `kustomization.yaml` files.
To create a new overlay, create a new directory with a new `kustomization.yaml` file that refers to the base resources to target.
Add any global modifers, the base resources to target and any modifications. **A valid base target is any directory with a `kustomization.yaml` file**.
See a detailed description of a kovan replica [here](./README-kovan-replica.md)
## Building
`kustomize` can be run in 2 different way, with the built in `kubectl` flag or using the stand alone binary. **The binary should be used for this repository** as the `kubectl` releases are lagging on the `envs` feature.
Using kubectl with the `-k` flag and a target directory will build and diff or apply the generated manifests.
```
kubectl diff -k ./bases/configmaps/
kubectl apply -k ./bases/configmaps/
```
Using a `kustomize` binary release, we simplay build the manifests and pipe them to `kubectl` on STDIN.
