|
| 1 | +--- |
| 2 | +sidebar_label: "Advanced topics" |
| 3 | +title: "Advanced topics" |
| 4 | +description: Advanced topics in Epinio application development environments |
| 5 | +keywords: [epinio, kubernetes, advanced topics] |
| 6 | +--- |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +There are some components, such as an Ingress controller and a Certificate Manager, |
| 11 | +required in a Kubernetes cluster before an Epinio installation. |
| 12 | +The Epinio helm chart doesn't deploy these components. |
| 13 | + |
| 14 | +### Ingress controller |
| 15 | + |
| 16 | +On a Kubernetes cluster, certain services need to be reachable from outside the cluster. |
| 17 | +For Epinio, the `API server` is one of them. |
| 18 | +Some applications deployed with Epinio might also need to be reachable from outside. |
| 19 | + |
| 20 | +One way to expose services externally is by creating |
| 21 | +[Ingress resources](https://kubernetes.io/docs/concepts/services-networking/ingress/). |
| 22 | +Ingress resources on their own, have no effect. |
| 23 | +They're merely descriptions of the needed routing. |
| 24 | +An Ingress controller handles the implementation of this routing. |
| 25 | + |
| 26 | +:::note |
| 27 | + |
| 28 | +Most clusters have an Ingress controller deployed by default. |
| 29 | +Install [Traefik](https://doc.traefik.io/traefik/providers/kubernetes-ingress/), |
| 30 | +or another, if an Ingress controller is absent. |
| 31 | +The project uses Traefik in Epinio CI to test Epinio. |
| 32 | + |
| 33 | +There is installation documentation for |
| 34 | +[Traefik](../installation/install_epinio.md#ingress-controller) |
| 35 | + |
| 36 | +::: |
| 37 | + |
| 38 | +Epinio creates an Ingress resource for the Epinio API server and each application deployed. |
| 39 | + |
| 40 | +### Cert-manager |
| 41 | + |
| 42 | +[Cert-manager documentation](https://cert-manager.io/docs/) |
| 43 | + |
| 44 | +Cert-manager is a Kubernetes controller that generates and renews certificates. |
| 45 | +You need these certificates to securely serve the endpoints over TLS |
| 46 | +(for example, the Epinio API server). |
| 47 | + |
| 48 | +Epinio supports options when it comes to certificate issuers |
| 49 | +(Let's Encrypt, your own private CA, self signed certs). |
| 50 | +Cert-manager simplifies the handling of certificate issuers within Epinio. |
| 51 | + |
| 52 | +You can read more about certificate issuers in the |
| 53 | +[certificate issuers documentation](../howtos/other/certificate_issuers.md) |
| 54 | + |
| 55 | +## Epinio installed components |
| 56 | + |
| 57 | +The official, supported, way to install Epinio is with the |
| 58 | +[Epinio Helm chart](https://artifacthub.io/packages/helm/epinio/epinio). |
| 59 | +This Helm chart installs Epinio and it's component dependencies, |
| 60 | +listed below, needed for Epinio to work. |
| 61 | + |
| 62 | +### Epinio API server |
| 63 | + |
| 64 | +The main component of Epinio is the API server. |
| 65 | +The same `epinio` binary is both the server and the CLI. |
| 66 | +The server starts with the `epinio server` command within a Kubernetes Pod, configured for Epinio. |
| 67 | + |
| 68 | +Epinio CLI and web UI functionality are implemented using |
| 69 | +the endpoints provided by the Epinio API server component. |
| 70 | +For example, when the user asks Epinio to "push" an application, |
| 71 | +the CLI contacts the "Upload", "Stage" and "Deploy" endpoints of the Epinio API to: |
| 72 | + |
| 73 | +- upload the application code |
| 74 | +- create a container image for the application using this code |
| 75 | +- run the application on the cluster. |
| 76 | + |
| 77 | +The Epinio API server runs on the cluster. |
| 78 | +It's reached using Kubernetes resources like |
| 79 | +Deployments, Services, Ingresses and Secrets. |
| 80 | + |
| 81 | +### Kubed |
| 82 | + |
| 83 | +[Kubed documentation](https://github.com/kubeops/kubed) |
| 84 | + |
| 85 | +Epinio installs Kubed to keep secrets, needed in more than one namespace, synchronized. |
| 86 | +For example, the image pull secret is needed in every application namespace |
| 87 | +so that Kubernetes can pull the built application images from the [Container Registry](#container-registry). |
| 88 | + |
| 89 | +Kubed makes sure that if the source secret changes, the copies change too. |
| 90 | + |
| 91 | +### Minio |
| 92 | + |
| 93 | +[Minio project link](https://github.com/minio/minio) |
| 94 | + |
| 95 | +Minio is a storage solution implementing the same API as [Amazon S3](https://aws.amazon.com/s3/). |
| 96 | + |
| 97 | +When the user pushes an application using a source code directory |
| 98 | +(with the [`epinio push`](../references/commands/cli/epinio_push.md) command), |
| 99 | +the CLI packages the source code into a tarball. |
| 100 | +It then uploads it to the Epinio API server. |
| 101 | +The API server copies that to the configured S3 storage for |
| 102 | +use during the staging of the application. |
| 103 | + |
| 104 | +When installing Epinio, you choose to use external S3 compatible storage, |
| 105 | +or let Epinio install one of Minio or s3gw on the cluster. |
| 106 | +You can see a [How-to here](../howtos/customization/setup_external_s3.md). |
| 107 | + |
| 108 | +### s3gw |
| 109 | + |
| 110 | +[The s3gw project link](https://github.com/aquarist-labs/s3gw) |
| 111 | + |
| 112 | +S3gw is a lightweight S3-compatible solution. |
| 113 | +You can specify it in the Epinio Helm chart as an alternative to Minio or an external S3 provider. |
| 114 | + |
| 115 | +### Container registry |
| 116 | + |
| 117 | +The result of Epinio's application staging is a container image. |
| 118 | +You use this image to create a Kubernetes deployment to run the application code. |
| 119 | +The staging job writes the image to a container registry. |
| 120 | +There is further information in the |
| 121 | +[detailed push process](detailed-push-process.md) documentation. |
| 122 | + |
| 123 | +By default, the Epinio installation deploys a container registry inside the Kubernetes cluster, making the process fast and convenient. |
| 124 | + |
| 125 | +Epinio comes with two consumers of this registry: |
| 126 | + |
| 127 | +- Staging job - pushing the images |
| 128 | +- Kubernetes - pulling the images when creating a deployment for the application |
| 129 | + |
| 130 | +All consumers should communicate with the registry using TLS to encrypt communication. |
| 131 | +Epinio controls the staging job and it ensures that it trusts the CA used to sign the registry certificate. |
| 132 | +Achieving the same for Kubernetes requires configuration that's impossible from within the cluster, |
| 133 | +therefore Epinio has no way to ensure that it trusts the CA. |
| 134 | +Epinio runs in a pod of the cluster and can't have permission to change cluster settings. |
| 135 | +Changes are only possible, from outside, by a cluster administrator. |
| 136 | + |
| 137 | +There are 3 options: |
| 138 | + |
| 139 | +1. Let the Epinio user manually configure Kubernetes to trust the CA |
| 140 | +1. Use a well-known trusted CA, so there's no configuration needed |
| 141 | +1. Don't encrypt the communication at all |
| 142 | + |
| 143 | +Currently Epinio doesn't support the first 2 options. |
| 144 | +If `containerregistry.enabled` is `true` during installation (default), |
| 145 | +Epinio makes Kubernetes pull the images un-encrypted (the last option above). |
| 146 | +If you need encryption, install the container registry manually |
| 147 | +and configure as an ["external" registry](../howtos/customization/setup_external_registry.md) |
| 148 | +during Epinio installation. |
| 149 | + |
| 150 | +:::note |
| 151 | + |
| 152 | +Communication between the staging job and container registry is TLS encrypted even when using the built-in container registry. |
| 153 | + |
| 154 | +::: |
| 155 | + |
| 156 | +## Other advanced topics |
| 157 | + |
| 158 | +### Git pushing |
| 159 | + |
| 160 | +The quick way of pushing an application, explained in |
| 161 | +[Quickstart: push an application](../tutorials/quickstart.md#push-an-application), |
| 162 | +uses a local directory containing a checkout of the application's sources. |
| 163 | + |
| 164 | +Internally this is a [complex](detailed-push-process.md) procedure. |
| 165 | +The client creates and uploads an archive (tarball or zip) |
| 166 | +from the sources to the Epinio server, |
| 167 | +copying into Epinio's internal (or external) S3 storage. |
| 168 | +It's then copied from that storage to a `PersistentVolumeClaim` |
| 169 | +to use in the job for staging. |
| 170 | +Staging is the compilation and creation of the docker image |
| 171 | +for use by the underlying Kubernetes cluster. |
| 172 | + |
| 173 | +The process is different when using the Epinio client's "git mode". |
| 174 | +In this mode [`epinio push`](../references/commands/cli/epinio_push.md) |
| 175 | +doesn't take a local directory of sources, |
| 176 | +but the location of a git repository and the id of the revision to use. |
| 177 | +The client then asks the Epinio server to pull those sources and store them to the S3 storage. |
| 178 | +The rest of the process is the same. |
| 179 | + |
| 180 | +The syntax is |
| 181 | + |
| 182 | +```console |
| 183 | +epinio push --name NAME --git GIT-REPOSITORY-URL,REVISION |
| 184 | +``` |
| 185 | + |
| 186 | +For comparison all the relevant syntax: |
| 187 | + |
| 188 | +```console |
| 189 | +epinio push |
| 190 | +epinio push MANIFEST-PATH |
| 191 | +epinio push --name NAME |
| 192 | +epinio push --name NAME --path DIRECTORY |
| 193 | +epinio push --name NAME --git GIT-REPOSITORY-URL,REVISION |
| 194 | +``` |
0 commit comments