diff --git a/deploy/charts/.gitignore b/deploy/charts/.gitignore new file mode 100644 index 0000000..67308ad --- /dev/null +++ b/deploy/charts/.gitignore @@ -0,0 +1,50 @@ +# Helm +*.tgz # Helm chart packages +.chart.lock # Helm chart lock file (optional, include if you want to lock dependencies) +.releases # Helm release tracking files +charts/ # Dependency charts (generated by 'helm dep up'; ignore unless you need to track them) + +# Kubernetes +kubeconfig # Local kubeconfig file + +# OS-specific +.DS_Store # macOS +Thumbs.db # Windows + +# Logs & temp files +*.log +*.tmp +*.bak +*.swp # Vim swap +*.swo + +# Build / deployment output +output/ +release/ +dist/ + +# Sensitive files (values and secrets) +secret.yaml +values-*.yaml # Environment-specific Helm values (e.g., values-prod.yaml) + +# Terraform (if used) +*.tfstate +*.tfstate.* +.terraform/ + +# IDE / Editor config +.idea/ # JetBrains IDEs +.vscode/ # Visual Studio Code +*.iml # JetBrains project files +*.code-workspace + +# Python (if used) +venv/ +__pycache__/ + +# Node.js (if used) +node_modules/ + +# Environment variables +.env +.env.* diff --git a/deploy/charts/Chart.yaml b/deploy/charts/Chart.yaml new file mode 100644 index 0000000..fb46213 --- /dev/null +++ b/deploy/charts/Chart.yaml @@ -0,0 +1,36 @@ +apiVersion: v2 +name: z3-stack +description: A Helm chart to deploy the z3 ecosystem on Kubernetes. +type: application +version: 0.0.1 +appVersion: "0.0.1" + +icon: https://zfnd.org/wp-content/uploads/2021/12/logo.svg +home: https://zfnd.org +sources: + - https://github.com/z3 + +maintainers: + - name: Electric Coin Company + email: support@electriccoin.co + +keywords: + - zcash + - blockchain + - cryptocurrency + - helm + - kubernetes + - z3 + +annotations: + artifacthub.io/description: "A Helm chart for deploying z3 ecosystem on Kubernetes." + artifacthub.io/license: "MIT" + artifacthub.io/source-url: https://github.com/ZcashFoundation/z3" + artifacthub.io/website-url: "https://electriccoin.co" + artifacthub.io/display-name: "z3 Stack" + artifacthub.io/version: "1.0.3" + artifacthub.io/changes: | + - Initial release of z3-Stack Helm chart + artifacthub.io/prerelease: "false" + artifacthub.io/kubeversion: ">=1.19.0" + diff --git a/deploy/charts/LICENSE b/deploy/charts/LICENSE new file mode 100644 index 0000000..819d398 --- /dev/null +++ b/deploy/charts/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 Electric Coin Company + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/deploy/charts/README.md b/deploy/charts/README.md new file mode 100644 index 0000000..6ce9d05 --- /dev/null +++ b/deploy/charts/README.md @@ -0,0 +1,107 @@ +# z3 Helm Chart - Plug and Play Zcash Ecosystem Deployment + +This Helm chart is designed to be a **plug and play solution** for deploying the z3 ecosystem on Kubernetes. With minimal configuration, you can easily deploy `zebra`, `zaino`, `zallet`, and `caddy` to run a fully functional z3 infrastructure. + +### Caddy as a Frontend + +By default, this chart uses **Caddy** as a web frontend for `zaino`, making it simple to expose the `zaino` service securely over HTTPS. Caddy automatically manages SSL certificates and provides a modern, user-friendly configuration for serving HTTP(S) traffic. This setup allows you to quickly expose `zaino` to external clients, such as mobile wallets, without worrying about complex web server configurations. + +### Customization Options + +Although the default configuration is ready to deploy and run, this Helm chart is highly customizable. You can easily adapt it to fit your specific infrastructure needs: + +- **Ingress or Internal Deployment**: If you prefer not to use `Caddy` or want to integrate the deployment with an existing ingress controller (like NGINX, Traefik, etc.), you can disable Caddy and configure your own ingress to expose `zaino` or other services. This makes the chart suitable for use in internal networks or environments where `Caddy` is not needed. + +- **Internal Infrastructure**: For deployments that don’t require public exposure (e.g., running on internal networks or for development purposes), you can modify the chart to adjust how services are exposed, allowing tighter integration with internal load balancers or private networking configurations. + +- **Custom Images and Resources**: All Docker images, resource limits, volume sizes, and other Kubernetes objects are fully customizable. You can override any value in the `values.yaml` file or through the `--set` flags in Helm, making it easy to adapt the deployment to your exact specifications. + +In summary, this Helm chart provides a turnkey solution to deploy the Zcash ecosystem (z3) quickly and securely. However, it is also flexible enough to be adapted for more advanced use cases, whether for public-facing deployments or internal infrastructures. + +## Components Overview + +This Helm chart includes several components that work together to create a complete Zcash infrastructure setup. Below is a brief explanation of each component, along with links to their respective GitHub repositories for more information. + +### Zebra +`zebra` is a Zcash full node implementation developed by the Zcash Foundation. It is responsible for maintaining the Zcash blockchain, validating transactions, and participating in the Zcash peer-to-peer network. zebra is written in Rust and focuses on security, performance, and modularity. It was developed to promote diversity in Zcash node software, making the network more robust and resilient. zebra is the preferred full node implementation for new deployments, and is configured by default in this Helm chart. + +- GitHub: [Zebra Repository](https://github.com/ZcashFoundation/zebra) + +### Zaino +TODO + +- GitHub: [Zaino Repository](https://github.com/zingolabs/zaino) + +### Zallet +TODO + +- GitHub: [Zallet Repository](https://github.com/zcash/wallet) + +### Caddy +`Caddy` is a modern web server that can be deployed as a frontend for `lightwalletd`. It provides easy HTTPS configuration, automatic certificate management, and other features like routing and reverse proxying. In this setup, Caddy handles incoming HTTP traffic for `lightwalletd`, ensuring secure connections and simplified configuration. + +- GitHub: [Caddy Repository](https://github.com/caddyserver/caddy) + +## Project Structure + +- **Chart.yaml**: Metadata of the Helm chart. +- **values.yaml**: Default values for deploying the Helm chart. +- **templates/**: Helm templates that generate Kubernetes manifests. +- **.gitignore**: Specifies files and directories to be ignored by Git. + +## Installation + +To use this Helm chart, you need to have [Helm](https://helm.sh/docs/intro/install/) installed. + +1. Navigate to the chart directory: + + ```bash + cd z3/deploy/charts + ``` +2. Add the repo + + ```bash + helm repo add z3 https://ZcashFoundation.github.io/z3/ + ``` + +3. Install the chart: + + ```bash + helm install z3/z3-stack + ``` + +4. If you need to override the default values, create a custom `values.yaml` and use the following command: + + ```bash + helm install z3/z3-stack --values + ``` + +## Configuration + +The following table lists the configurable parameters of the z3-stack Helm chart and their default values: + +| Parameter | Description | Default | Required | Possible values | +|--------------------------------|--------------------------------------------------------------|-------------------------------------------|----------|------------------------------------------| +| `zebra.enabled` | Enable Zebra node deployment | `True` | True | `False`, `True` | +| `zebra.name` | Name of the Zebra instance | `zebra` | True | Any string | +| `zebra.testnet` | Enable Zebra testnet mode | `False` | True | `False`, `True` | +| `zebra.image.repository` | Zebra Docker image repository | `zfnd/zebra` | True | Any valid image repository | +| `zebra.image.tag` | Zebra Docker image tag | `latest` | True | Any valid image tag | +| `zebra.replicas` | Number of Zebra replicas | `1` | True | Any integer >= 1 | +| `zebra.volumes.data.size` | Size of the Zebra data volume | `400Gi` | True | Any valid size (e.g., `400Gi`) | +| `zebra.volumes.data.storageClass` | Storage class for the Zebra data volume | `defaut` | True | Any valid storage class | +| `zebra.service.type` | Service type for Zebra | `ClusterIP` | True | `ClusterIP`, `NodePort`, `LoadBalancer` | +| `caddy.enabled` | Enable Caddy deployment (frontend for Lightwalletd) | `False` | True | `true`, `True` | +| `caddy.domain` | Domain for Caddy | `"lwd.example.com"` | True | Any valid domain | +| `caddy.email` | Email for SSL certificates | `"admin@example.com"` | True | Any valid email | +| `rpc.credentials.rpcUser` | RPC username | `5s3rn4m3` | True | Any string | +| `rpc.credentials.rpcPassword` | RPC password | `s3cr3tp4ssw0rd` | True | Any string | + +## Customizing the Deployment + +You can override the default values by creating a custom `values.yaml` or using the `--set` flag. For example: + +```bash +helm install z3/z3-stack +``` + diff --git a/deploy/charts/artifacthub-repo.yml b/deploy/charts/artifacthub-repo.yml new file mode 100644 index 0000000..c9ec943 --- /dev/null +++ b/deploy/charts/artifacthub-repo.yml @@ -0,0 +1,6 @@ +repository: + name: z3-stack + displayName: z3 Stack Helm Chart + description: A Helm chart to deploy the z3 ecosystem on Kubernetes. + type: helm + url: https://github.com/ZcashFoundation/z3 diff --git a/deploy/charts/templates/NOTES.txt b/deploy/charts/templates/NOTES.txt new file mode 100644 index 0000000..b1b79da --- /dev/null +++ b/deploy/charts/templates/NOTES.txt @@ -0,0 +1,13 @@ +{{- if .Values.caddy.enabled }} +To retrieve the external service IP (ClusterType: loadBalancer is required) of the Caddy server (which acts as the front-end for Lightwalletd), run the following command: + + kubectl get svc {{ .Release.Name }}-caddy -n {{ .Release.Namespace }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + +Once you have obtained the IP address from the above command, you will need to update your DNS records. Specifically, create or update an A record for your domain "{{ .Values.caddy.domain }}" to point to the retrieved IP address. +{{- end }} + + +NOTE: +{{- if or .Values.caddy.enabled }} +You may need to wait a moment before running these commands, as your cluster needs time to acquire the public IP. +{{- end }} diff --git a/deploy/charts/templates/caddy-configmap.yaml b/deploy/charts/templates/caddy-configmap.yaml new file mode 100644 index 0000000..b3872bd --- /dev/null +++ b/deploy/charts/templates/caddy-configmap.yaml @@ -0,0 +1,12 @@ +{{- if .Values.caddy.enabled }} +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ .Release.Name }}-caddy +data: + Caddyfile: | + {{ .Values.caddy.domain }} { + reverse_proxy h2c://{{ .Values.zaino.name }}-svc-service:9067 + tls {{ .Values.caddy.email }} + } +{{- end }} diff --git a/deploy/charts/templates/caddy-deployment.yaml b/deploy/charts/templates/caddy-deployment.yaml new file mode 100644 index 0000000..62b29c9 --- /dev/null +++ b/deploy/charts/templates/caddy-deployment.yaml @@ -0,0 +1,30 @@ +{{- if .Values.caddy.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ .Release.Name }}-caddy +spec: + replicas: 1 + selector: + matchLabels: + app: {{ .Release.Name }}-caddy + template: + metadata: + labels: + app: {{ .Release.Name }}-caddy + spec: + containers: + - name: caddy + image: caddy:latest + ports: + - containerPort: 80 + - containerPort: 443 + volumeMounts: + - name: caddy-config + mountPath: /etc/caddy/Caddyfile + subPath: Caddyfile + volumes: + - name: caddy-config + configMap: + name: {{ .Release.Name }}-caddy +{{- end }} \ No newline at end of file diff --git a/deploy/charts/templates/caddy-service.yaml b/deploy/charts/templates/caddy-service.yaml new file mode 100644 index 0000000..834472f --- /dev/null +++ b/deploy/charts/templates/caddy-service.yaml @@ -0,0 +1,19 @@ +{{- if .Values.caddy.enabled }} +apiVersion: v1 +kind: Service +metadata: + name: {{ .Release.Name }}-caddy +spec: + selector: + app: {{ .Release.Name }}-caddy + ports: + - protocol: TCP + port: 80 + targetPort: 80 + name: http + - protocol: TCP + port: 443 # Puerto HTTPS + targetPort: 443 + name: https + type: LoadBalancer +{{- end }} \ No newline at end of file diff --git a/deploy/charts/templates/zebrad-service.yaml b/deploy/charts/templates/zebrad-service.yaml new file mode 100644 index 0000000..227f97c --- /dev/null +++ b/deploy/charts/templates/zebrad-service.yaml @@ -0,0 +1,15 @@ +{{- if .Values.zebra.enabled }} +apiVersion: v1 +kind: Service +metadata: + name: {{ .Release.Name }}-{{ .Values.zebra.name }} +spec: + type: {{ .Values.zebra.service.type }} + selector: + app: {{ .Values.zebra.name }} + ports: + - port: 8232 + targetPort: 8232 + protocol: TCP + name: rpc +{{- end }} \ No newline at end of file diff --git a/deploy/charts/templates/zebrad-statefulset.yaml b/deploy/charts/templates/zebrad-statefulset.yaml new file mode 100644 index 0000000..27483c2 --- /dev/null +++ b/deploy/charts/templates/zebrad-statefulset.yaml @@ -0,0 +1,52 @@ +{{- if .Values.zebra.enabled }} +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: {{ .Release.Name }}-{{ .Values.zebra.name }} +spec: + replicas: {{ .Values.zebra.replicas }} + selector: + matchLabels: + app: {{ .Release.Name }}-{{ .Values.zebra.name }} + template: + metadata: + labels: + app: {{ .Release.Name }}-{{ .Values.zebra.name }} + spec: + securityContext: + runAsUser: 2001 + runAsGroup: 2001 + fsGroup: 2001 + fsGroupChangePolicy: "OnRootMismatch" # opcional (K8s >= 1.20) + containers: + - name: zebra + image: {{ .Values.zebra.image.repository }}:{{ .Values.zebra.image.tag }} + imagePullPolicy: {{ .Values.zebra.image.pullPolicy }} + env: + {{- with .Values.zebra.additionalEnv }} + {{- toYaml . | nindent 10 }} + {{- end }} + ports: + - containerPort: 8232 + name: zebra-rpc + - containerPort: 8233 + name: zebra-p2p + volumeMounts: + - name: {{ .Values.zebra.name }}-data + mountPath: /var/cache/zebrad-cache + resources: + {{- if .Values.zebra.resources }} + {{- toYaml .Values.zebra.resources | nindent 10 }} + {{- end }} + volumeClaimTemplates: + - metadata: + name: {{ .Values.zebra.name }}-data + spec: + accessModes: [ "ReadWriteMany" ] + resources: + requests: + storage: {{ .Values.zebra.volumes.data.size }} + {{- if .Values.zebra.volumes.data.storageClass }} + storageClassName: {{ .Values.zebra.volumes.data.storageClass }} + {{- end }} +{{- end }} diff --git a/deploy/charts/values.yaml b/deploy/charts/values.yaml new file mode 100644 index 0000000..5172635 --- /dev/null +++ b/deploy/charts/values.yaml @@ -0,0 +1,31 @@ +zebra: + enabled: True + name: zebra + testnet: false + image: + repository: zfnd/zebra + tag: latest + pullPolicy: IfNotPresent + replicas: 1 + additionalEnv: {} + volumes: + data: + size: 400Gi + storageClass: default + service: + type: ClusterIP + resources: + requests: + cpu: 2 + memory: 4Gi + limits: + memory: 16Gi + +## TODO: +zaino: +zallet: + +rpc: + credentials: + rpcUser: 5s3rn4m3 + rpcPassword: s3cr3tp4ssw0rd