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

Jump to bottom

Improve documentation for Nessie on Kubernetes #7997

Merged
merged 2 commits into from
Jan 29, 2024
Merged

Improve documentation for Nessie on Kubernetes #7997

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3736e67
Improve documentation for Nessie on Kubernetes
adutra Jan 27, 2024
3729e76
review
adutra Jan 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
174 changes: 5 additions & 169 deletions helm/nessie/README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
arrange:
- spark-s3.md
- keycloak.md
- minikube.md
- tls.md