Skip to content

Commit

Permalink
Improve documentation for Nessie on Kubernetes (#7997)
Browse files Browse the repository at this point in the history 
This commit introduces the following changes:

- The Helm charts page has been repurposed as "Nessie on Kubernetes" guide
  and improved with examples for different databases.
- Portions of the in-tree README for the Helm chart were repurposed (because
  they had little to do with Helm charts):
  - Text related to secrets was moved to the "Nessie on Kubernetes" guide.
  - Text related to minikube was moved to a new "Nessie on Minikube" guide.
- The Docker guide has been slightly augmented, notable to mention the
  different Nessie image repositories and how to pass environment variables.
  • Loading branch information
@adutra
adutra committed Jan 29, 2024
1 parent 47e710c commit bec6ee0
Show file tree
Hide file tree
Showing 10 changed files with 508 additions and 371 deletions.
174 changes: 5 additions & 169 deletions helm/nessie/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@ A Helm chart for Nessie.

* <https://github.com/projectnessie/nessie>

## Documentation

See [Nessie on Kubernetes](https://projectnessie.org/try/kubernetes/)
for more information.

## Installation

### From Helm repo
Expand Down Expand Up @@ -119,172 +124,3 @@ $ helm uninstall --namespace nessie-ns nessie
| tracing.endpoint | string | `"http://otlp-collector:4317"` | The collector endpoint URL to connect to (required). The endpoint URL must have either the http:// or the https:// scheme. The collector must talk the OpenTelemetry protocol (OTLP) and the port must be its gRPC port (by default 4317). See https://quarkus.io/guides/opentelemetry for more information. |
| tracing.sample | string | `"1.0d"` | Which requests should be sampled. Valid values are: "all", "none", or a ratio between 0.0 and "1.0d" (inclusive). E.g. "0.5d" means that 50% of the requests will be sampled. |
| versionStoreType | string | `"IN_MEMORY"` | Which type of version store to use: IN_MEMORY, ROCKSDB, DYNAMODB, MONGODB, CASSANDRA, JDBC, BIGTABLE. (Legacy version store types are: INMEMORY, ROCKS, DYNAMO, MONGO, TRANSACTIONAL. If you are using one of these legacy version store types, migrate your existing repositories to the new version store types using the nessie-quarkus-cli tool's export/import functionality.) |

## Using secrets

### Providing secrets for Dynamo Version Store

* Make sure you have a Secret in the following form:
```
> cat $PWD/awscreds
aws_access_key_id=YOURACCESSKEYDATA
aws_secret_access_key=YOURSECRETKEYDATA
```

* Create the secret from the given file
`kubectl create secret generic awscreds --from-env-file="$PWD/awscreds"`

* Now you can use `DYNAMO` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=DYNAMO`.

### Providing secrets for MongoDB

* Providing secrets for MongoDB is strongly recommended, but not enforced.
* Make sure you have a Secret in the following form:
```
> cat $PWD/mongodb-creds
mongodb_username=YOUR_USERNAME
mongodb_password=YOUR_PASSWORD
```

* Create the secret from the given file
`kubectl create secret generic mongodb-creds --from-env-file="$PWD/mongodb-creds"`

* The `mongodb-creds` secret will now be picked up when you use `MONGO` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=MONGO`.

### Providing secrets for Transactional Version Store

* Make sure you have a Secret in the following form:
```
> cat $PWD/postgres-creds
postgres_username=YOUR_USERNAME
postgres_password=YOUR_PASSWORD
```

* Create the secret from the given file
`kubectl create secret generic postgres-creds --from-env-file="$PWD/postgres-creds"`

* Now you can use `TRANSACTIONAL` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=TRANSACTIONAL`.

## Dev installation

* Install Minikube as described in https://minikube.sigs.k8s.io/docs/start/
* Install Helm as described in https://helm.sh/docs/intro/install/
* Start Minikube cluster: `minikube start`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install Nessie Helm chart: `helm install nessie -n nessie-ns helm/nessie`

### Ingress with Minikube

This is broadly following the example from https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/

* Start Minikube cluster: `minikube start`
* Enable NGINX Ingress controller: `minikube addons enable ingress`
* Verify Ingress controller is running: `kubectl get pods -n ingress-nginx`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install Nessie Helm chart with Ingress enabled:
```bash
helm install nessie -n nessie-ns helm/nessie \
--set ingress.enabled=true \
--set ingress.hosts[0].host='chart-example.local' \
--set ingress.hosts[0].paths[0]='/'
```

* Verify that the IP address is set:
```bash
kubectl get ingress -n nessie-ns
NAME CLASS HOSTS ADDRESS PORTS AGE
nessie nginx * 192.168.49.2 80 4m35s
```
* Use the IP from the above output and add it to `/etc/hosts` via `echo "192.168.49.2 chart-example.local" | sudo tee /etc/hosts`
* Verify that `curl chart-example.local` works

### OpenTelemetry Collector with Minikube

* Start Minikube cluster: `minikube start`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install cert-manager:

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml
```

* Install Jaeger Operator:

```bash
kubectl create namespace observability
kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.42.0/jaeger-operator.yaml -n observability
```

If the above command fails with "failed to call webhook [...] connection refused", then cert-manager
was not yet ready. Wait a few seconds and try again.

* Create a Jaeger instance in Nessie's namespace:

```bash
kubectl apply -n nessie-ns -f - <<EOF
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
name: jaeger
EOF
```

If the above command fails with "failed to call webhook [...] connection refused", then the Jaeger
Operator was not yet ready. Wait a few seconds and try again.

* Install Nessie Helm chart with OpenTelemetry Collector enabled:

```bash
helm install nessie -n nessie-ns helm/nessie \
--set tracing.enabled=true \
--set tracing.endpoint=http://jaeger-collector:4317
```

* Forward ports to Jaeger UI and Nessie UI:

```bash
kubectl port-forward -n nessie-ns service/nessie 19120:19120 &
kubectl port-forward -n nessie-ns service/jaeger-query 16686:16686 &
```

* Open the following URLs in your browser:
* Nessie UI (to generate some traces): http://localhost:19120
* Jaeger UI (to retrieve the traces): http://localhost:16686/search

To kill the port forwarding processes, run:

```bash
killall -9 kubectl
```

### Custom Docker images for Nessie with Minikube

You can modify Nessie's code and deploy it to Minikube.

Once you've satisfied with your changes, build the project with:

```bash
./gradlew :nessie-quarkus:quarkusBuild
```

Then build the Docker image and deploy it as follows:

```bash
eval $(minikube docker-env)
docker build -f ./tools/dockerbuild/docker/Dockerfile-jvm -t nessie-test:latest ./servers/quarkus-server
```

Then deploy Nessie with the custom Docker image:

```bash
helm install nessie -n nessie-ns helm/nessie \
--set image.repository=nessie-test \
--set image.tag=latest
```

### Stop/Uninstall everything in Dev

```sh
helm uninstall --namespace nessie-ns nessie
minikube delete
```
174 changes: 5 additions & 169 deletions helm/nessie/README.md.gotmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ helm-docs --chart-search-root=helm

{{ template "chart.requirementsSection" . }}

## Documentation

See [Nessie on Kubernetes](https://projectnessie.org/try/kubernetes/)
for more information.

## Installation

### From Helm repo
Expand All @@ -50,172 +55,3 @@ $ helm uninstall --namespace nessie-ns nessie
```

{{ template "chart.valuesSection" . }}

## Using secrets

### Providing secrets for Dynamo Version Store

* Make sure you have a Secret in the following form:
```
> cat $PWD/awscreds
aws_access_key_id=YOURACCESSKEYDATA
aws_secret_access_key=YOURSECRETKEYDATA
```

* Create the secret from the given file
`kubectl create secret generic awscreds --from-env-file="$PWD/awscreds"`

* Now you can use `DYNAMO` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=DYNAMO`.

### Providing secrets for MongoDB

* Providing secrets for MongoDB is strongly recommended, but not enforced.
* Make sure you have a Secret in the following form:
```
> cat $PWD/mongodb-creds
mongodb_username=YOUR_USERNAME
mongodb_password=YOUR_PASSWORD
```

* Create the secret from the given file
`kubectl create secret generic mongodb-creds --from-env-file="$PWD/mongodb-creds"`

* The `mongodb-creds` secret will now be picked up when you use `MONGO` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=MONGO`.

### Providing secrets for Transactional Version Store

* Make sure you have a Secret in the following form:
```
> cat $PWD/postgres-creds
postgres_username=YOUR_USERNAME
postgres_password=YOUR_PASSWORD
```

* Create the secret from the given file
`kubectl create secret generic postgres-creds --from-env-file="$PWD/postgres-creds"`

* Now you can use `TRANSACTIONAL` as the version store when installing Nessie via `helm install -n nessie-ns nessie helm/nessie --set versionStoreType=TRANSACTIONAL`.

## Dev installation

* Install Minikube as described in https://minikube.sigs.k8s.io/docs/start/
* Install Helm as described in https://helm.sh/docs/intro/install/
* Start Minikube cluster: `minikube start`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install Nessie Helm chart: `helm install nessie -n nessie-ns helm/nessie`

### Ingress with Minikube

This is broadly following the example from https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/

* Start Minikube cluster: `minikube start`
* Enable NGINX Ingress controller: `minikube addons enable ingress`
* Verify Ingress controller is running: `kubectl get pods -n ingress-nginx`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install Nessie Helm chart with Ingress enabled:
```bash
helm install nessie -n nessie-ns helm/nessie \
--set ingress.enabled=true \
--set ingress.hosts[0].host='chart-example.local' \
--set ingress.hosts[0].paths[0]='/'
```

* Verify that the IP address is set:
```bash
kubectl get ingress -n nessie-ns
NAME CLASS HOSTS ADDRESS PORTS AGE
nessie nginx * 192.168.49.2 80 4m35s
```
* Use the IP from the above output and add it to `/etc/hosts` via `echo "192.168.49.2 chart-example.local" | sudo tee /etc/hosts`
* Verify that `curl chart-example.local` works

### OpenTelemetry Collector with Minikube

* Start Minikube cluster: `minikube start`
* Create K8s Namespace: `kubectl create namespace nessie-ns`
* Install cert-manager:

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml
```

* Install Jaeger Operator:

```bash
kubectl create namespace observability
kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.42.0/jaeger-operator.yaml -n observability
```

If the above command fails with "failed to call webhook [...] connection refused", then cert-manager
was not yet ready. Wait a few seconds and try again.

* Create a Jaeger instance in Nessie's namespace:

```bash
kubectl apply -n nessie-ns -f - <<EOF
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
name: jaeger
EOF
```

If the above command fails with "failed to call webhook [...] connection refused", then the Jaeger
Operator was not yet ready. Wait a few seconds and try again.

* Install Nessie Helm chart with OpenTelemetry Collector enabled:

```bash
helm install nessie -n nessie-ns helm/nessie \
--set tracing.enabled=true \
--set tracing.endpoint=http://jaeger-collector:4317
```

* Forward ports to Jaeger UI and Nessie UI:

```bash
kubectl port-forward -n nessie-ns service/nessie 19120:19120 &
kubectl port-forward -n nessie-ns service/jaeger-query 16686:16686 &
```

* Open the following URLs in your browser:
* Nessie UI (to generate some traces): http://localhost:19120
* Jaeger UI (to retrieve the traces): http://localhost:16686/search

To kill the port forwarding processes, run:

```bash
killall -9 kubectl
```

### Custom Docker images for Nessie with Minikube

You can modify Nessie's code and deploy it to Minikube.

Once you've satisfied with your changes, build the project with:

```bash
./gradlew :nessie-quarkus:quarkusBuild
```

Then build the Docker image and deploy it as follows:

```bash
eval $(minikube docker-env)
docker build -f ./tools/dockerbuild/docker/Dockerfile-jvm -t nessie-test:latest ./servers/quarkus-server
```

Then deploy Nessie with the custom Docker image:

```bash
helm install nessie -n nessie-ns helm/nessie \
--set image.repository=nessie-test \
--set image.tag=latest
```

### Stop/Uninstall everything in Dev

```sh
helm uninstall --namespace nessie-ns nessie
minikube delete
```
5 changes: 5 additions & 0 deletions site/docs/guides/_config
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
arrange:
- spark-s3.md
- keycloak.md
- minikube.md
- tls.md

0 comments on commit bec6ee0

Please sign in to comment.