Skip to content

Commit d0c3834

Browse files
author
ppanero
committed
deployment: add helm charts, configuration and openshift docs
1 parent b7b70f1 commit d0c3834

File tree

6 files changed

+320
-2
lines changed

6 files changed

+320
-2
lines changed

‎docs/deployment/configuration.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Configuration
2+
3+
This section explain the current configuration options that are available for the different components that are deployed but the Helm charts.
4+
5+
## Global
6+
7+
The is only one mandatory configuration, which is the host name, for example:
8+
9+
```yaml
10+
host: your-rdm-instance.com
11+
```
12+
13+
Moreover, the services can be deployed along, note that it is recommended to deploy separatelly Elasticsearch and PostgreSQL for a production deployment.
14+
Therefore, by default only `redis` and `rabbitmq` are enabled. Example configuration:
15+
16+
``` yaml
17+
postgresql:
18+
inside_cluster: false
19+
20+
elasticsearch:
21+
inside_cluster: false
22+
```
23+
24+
!!! info "inside_cluster availability
25+
Note that the `inside_cluster` variable is supported for `redis`, `rabbitmq`, `elasticsearch`, `postgresql` and `haproxy`. The rest of the components
26+
are mandatory.
27+
28+
## HAProxy
29+
30+
You can change the number of connections allowed by the haproxy with the `maxconn` variable:
31+
32+
```
33+
haproxy:
34+
maxconn: 100
35+
```
36+
37+
!!! warning "Only one parent element"
38+
By default the HAProxy is enabled, `inside_cluster` has the value `true`, nonetheless if you decide to set it, you only need
39+
to specify once the `haproxy` parent in the yaml file. Otherwise the last one will override the previous. It should be something like:
40+
``` yaml
41+
haproxy:
42+
inside_cluster: true
43+
maxconn: 100
44+
```
45+
## Nginx
46+
47+
The charts allow you to configure the amount of connections per nginx node (replica) and the amount of nodes:
48+
49+
```
50+
nginx:
51+
max_conns: 100
52+
replicas: 2
53+
```
54+
55+
## Web nodes
56+
57+
The web nodes host the WSGI application, in order to be scalable you can configure the number of "nodes", called replicas, how many processes do each node run and with how many threads per process. The only mandatory parameter is the docker image (`image`) that should get as value the url where to pull the image from.
58+
59+
In addition, you can add automatic scaling, by setting minimum and maximum replicas and the threshold of cpu usage in which a new node should be spawned. For example, with a threshold of 65%, it meand that when the average CPU utilization of the nodes reaches 65% a new node will de spawned, till it reaches the setted maximum:
60+
61+
``` yaml
62+
web:
63+
image: your/invenio-image
64+
replicas: 6
65+
uwsgi:
66+
processes: 6
67+
threads: 4
68+
autoscaler:
69+
enabled: false
70+
# Scale when CPU usage gets to
71+
scaler_cpu_utilization: 65
72+
max_web_replicas: 10
73+
min_web_replicas: 2
74+
```
75+
76+
## Worker nodes
77+
78+
Finally, the worker nodes. By default they are enabled, but you can cancel their deployment by setting `enabled` to `false`. If enabled, in the same fashion than the web nodes
79+
they require an `image`.
80+
81+
In addition, you can configure how many worker nodes (replicas) will be deployed, which the application they will run, with which concurrency level and the logging level.
82+
83+
``` yaml
84+
worker:
85+
enabled: true
86+
image: your/invenio-image
87+
# Invenio Celery worker application
88+
app: invenio_app.celery
89+
# Number of concurrent Celery workers per pod
90+
concurrency: 2
91+
log_level: INFO
92+
replicas: 2
93+
```

‎docs/deployment/index.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# How can I deploy InvenioRDM?
2+
3+
You can deploy InvenioRDM in several ways. You can install it in your [local computer](../develop/index.md) to have more easily customizable environment, otherwise you can deploy a [containerized environment](../preview/index.md) that demonstrates the setup of all components runnning in docker containers. In this section it is explained how to deploy in a closer-to-production manner.
4+
5+
!!! warning "Do not deploy as-is in production"
6+
Please note that it is mentioned as "closer-to-production", this is because even if the designed architecture can scale and withstand the load of a production service (It has been tested to stand peaks of up to 180 requests/s), the security configurations might not be enough and you should review it. In addition, it can deploy the extra services (Elasticsearch and PostgreSQL) along with them, however this ones are not configured with redundancy and persistance.
7+
8+
## Helm Charts
9+
10+
[Helm](https://helm.sh) is the package manager for [Kubernetes](https://kubernetes.io/). This means, that by using Helm charts you can deploy InvenioRDM in any cloud provider that supports Kubernetes (e.g. OpenShift clusters, Google Cloud, Amazon Web Services, IBM Cloud).
11+
12+
**What is a Helm chart?**
13+
14+
A Helm chart is a definition of the architecture of the system, meaning how all components interconnect with each other (In a similar fashion that a `docker-compose` file).
15+
16+
In addition, Helm allows you to **install, version and upgrade and rollback** your InvenioRDM installation in an easy way. You can find more information about Helm [here](https://helm.sh/docs/intro/quickstart/).
17+
18+
### Charts description
19+
20+
The currents charts propose the following architecture:
21+
22+
- HAProxy as entry point. It provides load balancing and queuing of the requests.
23+
- Nginx as reverse proxy. It serves as reverse proxy, to help HAproxy and uWSGI "talk" the same language (protocol).
24+
- Web application nodes, running the uWSGI application.
25+
- Redis and RabbitMQ come along in containers.
26+
- Elasticsearch and PostgreSQL can be added to the deployment, however they are not configured in-depth and therefore not suited for more than demo purposes.
27+
28+
For more in-depth documentation see the [services description](services.md) and the configuration available [here](configuration.md).
29+
30+
## Pre-Requirements
31+
32+
- [Helm](https://helm.sh/docs/intro/install/) version 3.x
33+
- Adding the [helm-invenio](https://github.com/inveniosoftware/helm-invenio) repository
34+
35+
``` console
36+
$ helm repo add helm-invenio https://inveniosoftware.github.io/helm-invenio/
37+
$ helm repo update
38+
$ helm search invenio
39+
40+
NAME CHART VERSION APP VERSION DESCRIPTION
41+
helm-invenio/invenio 0.2.0 1.16.0 Open Source framework for large-scale digital repositories
42+
helm-invenio/invenio 0.1.0 1.16.0 Open Source framework for large-scale digital repositories
43+
```
44+
45+
You can also install by cloning from GitHub by cloning the repository:
46+
47+
```
48+
$ git clone https://github.com/inveniosoftware/helm-invenio.git
49+
$ cd helm-invenio/
50+
```
51+
52+
Then you will need, to reference the `./invenio` folder rather than the chart name (`helm-invenio/invenio`).
53+
54+
## Supported Platforms
55+
56+
!!! warning "Only compatible with OpenShift"
57+
Pleas note that currently these Helm charts are only compatible with OpenShift.
58+
59+
- [OpenShift](openshift.md)
60+
- [Kubernetes](kubernetes.md)

‎docs/deployment/openshift.md

Lines changed: 160 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,162 @@
11
# OpenShift
22

3-
Coming soon
3+
## Pre-Requirements
4+
5+
- [Global deployment pre-requirements](index.md#pre-requirements)
6+
- [OpenShift CLI](https://docs.openshift.com/container-platform/4.3/cli_reference/openshift_cli/getting-started-cli.html#cli-installing-cli_cli-developer-commands) version 3.11+
7+
8+
9+
## Deploying InvenioRDM
10+
11+
First of all login and select the right project in your OpenShift cluster:
12+
13+
```console
14+
$ oc login <your.openshift.cluster>
15+
$ oc project invenio
16+
```
17+
18+
### Secrets
19+
20+
Before deploying in need to provide the credentials so the application can access the different services:
21+
22+
**Database secrets:**
23+
24+
```console
25+
$ POSTGRESQL_PASSWORD=$(openssl rand -hex 8)
26+
$ POSTGRESQL_USER=invenio
27+
$ POSTGRESQL_HOST=db
28+
$ POSTGRESQL_PORT=5432
29+
$ POSTGRESQL_DATABASE=invenio
30+
$ oc create secret generic \
31+
--from-literal="POSTGRESQL_PASSWORD=$POSTGRESQL_PASSWORD" \
32+
--from-literal="SQLALCHEMY_DB_URI=postgresql+psycopg2://$POSTGRESQL_USER:$POSTGRESQL_PASSWORD@$POSTGRESQL_HOST:$POSTGRESQL_PORT/$POSTGRESQL_DATABASE" \
33+
db-secrets
34+
secret "db-secrets" created
35+
```
36+
37+
**RabbitMQ secrets:**
38+
39+
```console
40+
$ RABBITMQ_DEFAULT_PASS=$(openssl rand -hex 8)
41+
$ oc create secret generic \
42+
--from-literal="RABBITMQ_DEFAULT_PASS=$RABBITMQ_DEFAULT_PASS" \
43+
--from-literal="CELERY_BROKER_URL=amqp://guest:$RABBITMQ_DEFAULT_PASS@mq:5672/" \
44+
mq-secrets
45+
secret "mq-secrets" created
46+
```
47+
48+
**Elasticsearch secrets:**
49+
50+
!!! info "Elasticaserch variables"
51+
Currently, and until [invenio-search#198](https://github.com/inveniosoftware/invenio-search/issues/198) has been addressed, the Elasticsearch configuration
52+
has to be loaded in a single environment variable.
53+
54+
``` console
55+
$ export INVENIO_SEARCH_ELASTIC_HOSTS="[{'host': 'localhost', 'timeout': 30, 'port': 9200, 'use_ssl': True, 'http_auth':('USERNAME_CHANGEME', 'PASSWORD_CHANGEME')}]"
56+
$ oc create secret generic \
57+
--from-literal="INVENIO_SEARCH_ELASTIC_HOSTS=$INVENIO_SEARCH_ELASTIC_HOSTS" \
58+
elasticsearch-secrets
59+
```
60+
61+
!!! info "Extra configuration is possible"
62+
Note that you might need to add extra configuration to the elasticsearch hosts, sucha as vertificate verification (`verify_certs`), prefixing (`url_prefix`) and more.
63+
64+
### Install InvenioRDM
65+
66+
Before installing you need to configure two things, the rest are optional and you can read more about it [here](configuration.md):
67+
68+
- Your host in a `values.yaml` file.
69+
- The web/worker docker images.
70+
71+
``` yaml
72+
host: yourhost.localhost
73+
74+
web:
75+
image: your/invenio-image
76+
77+
worker:
78+
image: your/invenio-image
79+
```
80+
81+
The next step is the installation itself, with your own configuration in the `values.yaml`. If you added the repository you can install it by using the chart name and the desired version:
82+
83+
``` console
84+
$ helm install -f values.yaml invenio helm-invenio/invenio --version 0.2.0
85+
```
86+
87+
If you want to install from GitHub, in a clone you can do so as follows:
88+
89+
``` console
90+
$ cd helm-invenio/
91+
$ helm install -f values.yaml invenio ./invenio [--disable-openapi-validation]
92+
```
93+
94+
In both cases the output will be:
95+
96+
``` console
97+
NAME: invenio
98+
LAST DEPLOYED: Mon Mar 9 16:25:15 2020
99+
NAMESPACE: default
100+
STATUS: deployed
101+
REVISION: 1
102+
TEST SUITE: None
103+
NOTES:Invenio is ready to rock :rocket:
104+
```
105+
106+
!!! warning "Bypassing openapi validation"
107+
We must pass `--disable-openapi-validation` as there is currently a problem with OpenShift objects and Helm when it comes to client side validation, see [issue](https://github.com/openshift/origin/issues/24060).
108+
109+
110+
### Setup the instance
111+
112+
Once the instance has been installed you have to set up the services. Note that this step is only needed the first time, if you are upgrading the instance this is not needed.
113+
114+
Get a bash terminal in a web pod:
115+
116+
```console
117+
$ oc get pods
118+
$ oc exec -it <web-pod> bash
119+
```
120+
121+
Setup the instance using the `invenio` commands:
122+
123+
``` console
124+
$ . scl_source enable rh-python36
125+
$ invenio db init # If the db does not exist already, otherwise `create` is enough
126+
$ invenio db create
127+
$ invenio index init
128+
$ invenio index queue init purge
129+
$ invenio files location --default 'default-location' $(invenio shell --no-term-title -c "print(app.instance_path)")'/data'
130+
$ invenio roles create admin
131+
$ invenio access allow superuser-access role admin
132+
```
133+
134+
#### Launching jobs
135+
136+
**One time job**
137+
138+
In some cases you might want to run jobs, for example to populate the instance with records.
139+
140+
``` console
141+
$ oc process -f job.yml --param JOB_NAME='demo-data-1' \
142+
--param JOB_COMMAND='invenio rdm-records demo' | oc create -f -
143+
```
144+
145+
**Cron job**
146+
147+
Now imagine you might have some bulk record creation that needs to be indexed, or any other task that you have to do every certain period of time.
148+
For that you can define cronjobs:
149+
150+
``` console
151+
$ oc process -f cronjob.yml --param JOB_NAME=index-run \
152+
--param JOB_COMMAND=invenio index run -d | oc create -f -
153+
```
154+
155+
### Upgrade your instance
156+
157+
If you have performed some changes to your instance (e.g. configuration) or you want to upgrade the version of the charts, you can do so with
158+
the `upgrade` command of `helm`, note that you still need to disable the openapi validation which is only supoprted after version 3.1.2:
159+
160+
``` console
161+
$ helm upgrade -f values.yaml --disable-openapi-validation
162+
```

‎docs/deployment/services.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Services
2+
3+
Coming soon

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,4 @@ Ready to deploy into production? Follow these guides to put a small instance in
4949
production and learn the avenues to take and decisions to make to grow it.
5050
Whether you use Openshift or Kubernetes, we've got you covered.
5151

52-
[> Deployment Guides](deployment/openshift.md)
52+
[> Deployment Guides](deployment/index.md)

‎mkdocs.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ nav:
4343
- Add your extensions: 'extensions/custom.md'
4444
- S3 Storage: 'extensions/s3.md'
4545
- Deploy:
46+
- How can I deploy it?: 'deployment/index.md'
47+
- System components: 'deployment/services.md'
48+
- Configuration: 'deployment/configuration.md'
4649
- Kubernetes: 'deployment/kubernetes.md'
4750
- OpenShift: 'deployment/openshift.md'
4851

0 commit comments

Comments
 (0)