README.md.gotmpl

# Percona Everest

This helm chart deploys Percona Everest.

Useful links:
- [Percona Everest Documentation](https://docs.percona.com/everest/index.html)
- [Percona Everest GitHub](https://github.com/percona/everest)
- [Deploying with ArgoCD](./docs/argocd.md)
- [Installing on OpenShift](./docs/openshift.md)

## Usage

### 1. Add the Percona Helm repository

```sh
helm repo add percona https://percona.github.io/percona-helm-charts/
helm repo update
```

### 2. Install Everest
```sh
helm install everest-core percona/everest \
    --namespace everest-system \
    --create-namespace
```

Notes:
* This command deploys the Everest components in the `everest-system` namespace. Currently, we do not support specifying a different namespace for Everest.
* Additionally, it also deploys a new namespace called `everest` for your databases and the database operators.
* If you prefer to manage your database namespace separately, you may set `dbNamespace.enabled=false`.
* You may override the name of the database namespace using the `dbNamespace.namespaceOverride` parameter.
* By default, all database operators are installed in your database namespace. You may override this by specifying one or more of the following: [`dbNamespace.pxc=false`, `dbNamespace.pg=false`, `dbNamespace.psmdb=false`].
* We currently do not support installation without the use of chart hooks. I.e, the use of `--no-hooks` is not supported during installation.

### 3. Retrieve the admin password

Once the installation is complete, you may retrieve the admin credentials using the following command:
```sh
kubectl get secret everest-accounts -n everest-system -o jsonpath='{.data.users\.yaml}' | base64 --decode  | yq '.admin.passwordHash'
```

You may open the Everest UI by port-forwarding the service to your local machine:

```sh
kubectl port-forward svc/everest -n everest-system 8080:8080
```

Notes:
* The default username to login to the Everest UI is `admin`.
* You may specify a different default admin password using `server.initialAdminPassword` parameter during installation.
* The default admin password is stored in plain text. It is highly recommended to update the password using `everestctl` to ensure that the passwords are hashed.

### 4. Deploy additional database namespaces

After Everest is successfully running, you may create additional database namespaces using the `everest-db-namespace` Helm chart.
If you had set `dbNamespaces.enabled=false` in the previous step, you may deploy a database namespaces using the following command:

```sh
helm install everest \
    percona/everest-db-namespace \
    --create-namespace \
    --namespace everest
```

Notes:
* By default, all database operators are installed in your database namespace. You may override this by specifying one or more of the following: [`dbNamespace.pxc=false`, `dbNamespace.pg=false`, `dbNamespace.psmdb=false`].
* We currently do not support installation without the use of chart hooks. I.e, the use of `--no-hooks` is not supported during installation.

#### 4.1 Deploying additional operators to an existing database namespace

If you have an existing database namespace and would like to deploy additional operators to it, you may do so using the following command:

```sh
helm upgrade everest \
    percona/everest-db-namespace \
    --namespace [NAMESPACE]
    --pxc=true \
    --pg=true
```

The above example assumes that the MongoDB operator is already installed in the database namespace and you would like to install the Percona XtraDB Cluster and PostgreSQL operators.

Notes:
* Removing a database operator from a namespace is not supported. You may only add additional operators.

### 5. Uninstall

#### 5.1 Uninstalling database namespaces

If you created any database namespaces (apart from the one installed by default), you must delete them first.

```sh
helm uninstall everest -n <your_db_namespace>
kubectl delete ns <your_db_namespace>
```

Notes:
* This runs a chart hook that cleans up your database resources first. While it is not recommended, you may skip this step by specifying `cleanupOnUninstall=false`.

#### 5.2 Uninstalling Everest

```sh
helm uninstall everest-core -n everest-system
kubectl delete ns everest-system
```

### 6. Upgrade

#### 6.1 Upgrade CRDs

As of Helm v3, CRDs are not automatically updated during a Helm upgrade. You must manually upgrade the CRDs.

```sh
VERSION=<Next version> # e.g. v1.3.0
kubectl apply -k https://github.com/percona/everest-operator/config/crd?ref=$(VERSION) --server-side
```

#### 6.2 Upgrade Helm Releases

Upgrade the Helm release for Everest (core components):
```sh
helm upgrade everest-core percona/everest --namespace everest-system --version $(VERSION)
```

Upgrade the Helm release for the database namespace (if applicable):
```sh
helm upgrade everest percona/everest-db-namespace --namespace [DB NAMESPACE] --version $(VERSION)
```

Notes:
* :warning: When specifying values during an upgrade (i.e, using `--set`, `--set-json`, `--values`, etc.), Helm resets all the other values
to the defaults built into the chart. To preserve the previously set values, you must use the `--reuse-values` flag. 
Alternatively, provide the full set of values, including any overrides applied during installation.
* It is recommended to upgrade 1 minor release at a time, otherwise you may run into unexpected issues.
* It is recommended to upgrade to the latest patch release first before upgrading to the next minor release.
* To ensure that the upgrade happens safely, we run a pre-upgrade hook that runs a series of checks. This can be disabled by setting `upgrade.preflightChecks=false`.
However, in doing so, a safe upgrade cannot be guaranteed.

## Configuration

The following table shows the configurable parameters of the Percona Everest chart and their default values.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
{{- range .Values }}
| {{ .Key }} | {{ .Type }} | {{ .Default }} | {{ .AutoDescription }} |
{{- end }}