Introduction

From App to URL in one step.

What problem does Epinio solve

Epinio makes it easy for developers to deploy their applications to Kubernetes. Easy means:

  • No previous experience with Kubernetes is required
  • No steep learning curve
  • Quick local setup with zero configuration
  • Deploying to production similar to development

Kubernetes is becoming the de-facto standard for container orchestration. Developers may want to use Kubernetes for all the benefits it provides or may have to do so because that's what their Ops team has chosen. Whatever the case, using Kubernetes is not simple. It has a steep learning curve and doing it right is a full time job. Developers should spend their time working on their applications, not doing operations.

Epinio is adding the needed abstractions and intelligence to allow Developers to use Kubernetes as a PaaS (Platform as a Service).

Features

  • Security
    • mTLS: Epinio uses linkerd to secure all communication between epinio components inside the kubernetes cluster
    • Basic Authentication to access the API.
  • Epinio Clients
    • Web UI
    • Epinio CLI
  • Apps
    • CRUD operations of your app. (An app can be a tarball or in a github repo)
    • Cloud Native Buildpacks provide the runtime environment for your apps
  • Services
    • CRUD operations of your service. A service can be a database, SaaS etc. A service can be an external component or can be created using epinio service
    • Bind services to apps.

Quickstart

Follow the quickstart tutorial to get started with Epinio.

QuickStart

If you have not already installed epinio follow these links

In this tutorial, you will learn how to create a namespace and how to push, list and delete an application in it.

Push an application

Clone the sample app

If you just want an application that works use the one inside the sample-app directory.

You can copy it to your system with the following commands:

git clone https://github.com/epinio/epinio.git
cd epinio/assets/

Push an app

There are two ways to push an application:

  1. You can provide an Application Manifest which contains the required configuration for the applications.
epinio push manifest.yaml
  1. You can provide the configuration as parameters in which case the parameter --name is mandatory. Because of the default route the name has to be unique across all namespaces.
epinio push --name sample --path samle-app

Note that the --path parameter is optional. If not specified the current working directory will be used. Always ensure that the chosen directory contains a supported application.

If you want to know what applications are supported in Epinio, please read the notes about supported applications.

We also provide information about the more advanced git model.


Note: If you want to know the details of the epinio push

process, please read the detailed push docs


Check that your application is working

After the application has been pushed, a unique URL is printed which you can use to access your application. If you don't have this URL available anymore you can find it again by running:

epinio app show sample

("Routes" is the part your are looking for)

Go ahead and open the application route in your browser!

List all commands

To see all the applications you have deployed use the following command:

epinio apps list

Delete an application

To delete the application you just deployed run the following command:

epinio delete sample

Create a separate namespace

If you want to keep your various application separated, you can use the concept of namespaces. Create a new namespace with this command:

epinio namespace create newspace

To start deploying application to this new namespace you have to "target" it:

epinio target newspace

After this and until you target another namespace, whenever you run epinio push you will be deploying to this new namespace.

Installation

The Epinio CLI will typically run on a host, which will need network access to your kubernetes cluster. Usually you will use the same host to run tooling, like e.g. "kubectl" and "helm".

The compiled binary will use about 40-50MB disk space, incl. local configuration files.

System requirements

Epinio is a Kubernetes application and thus needs a running Kubernetes cluster for installation.

See system requirements about the Kubernetes environment Epinio expects to run on.

Install the Epinio CLI

Refer to Install the Epinio CLI.

Installation Methods (in Cluster)

Beside advanced installation options, there are two ways of installing Epinio:

  1. Installation using a MagicDNS Service
  • For test environments. This should work on nearly any kubernetes distribution. Epinio will try to automatically create a magic DNS domain, e.g. 10.0.0.1.omg.howdoi.website.
  1. Installation using a Custom Domain
  • For test and production environments. You will have to define a system domain, e.g. test.example.com.

Installation on Specific Kubernetes Offerings

Kubernetes Cluster Requirements

For the Epinio server, and related deployments we recommend to consider the following resources:

  • x86_64, ARM32, or ARM64 architecture
  • Supported operating systems
  • Kubernetes versions 1.18 .. 1.21
  • 2-4 VCPUs
  • 8GB RAM (system memory + 4GB)
  • 10GB Disk space (system disk + 5GB)

In addition, extensive requirements for your workload (apps) would add to that.

Storage Class

A default storage class (with annotation storageclass.kubernetes.io/is-default-class: "true") is needed.

Load Balancer

Epinio (Traefik) requires a load-balancer. Depending on your target infrastructure, you can use embedded ones (like on Public Cloud, k3d, aso.) or configure your own. Also see Provision of External IP for LoadBalancer service type in Kubernetes for more information.

Troubleshooting

While Kubernetes 1.22 is supported there is an issue when the container runtime is containerd > 1.5.6. The pack cli is placing too much information into the image layers. The relevant issue is: https://github.com/paketo-buildpacks/full-builder/issues/415

Installation of the Epinio CLI

Before you begin

If not done already, refer to System Requirements.

Install Dependencies

  • kubectl: Follow instructions here: https://kubernetes.io/docs/tasks/tools/#kubectl
  • helm: Follow instructions here: https://helm.sh/docs/intro/install/

Install Epinio CLI

Download the Binary

Find the latest version at Releases. Run one of the commands below, and replace <epinio-version> with the version of your choice, e.g. "v0.1.0".

Linux
curl -o epinio -L https://github.com/epinio/epinio/releases/download/<epinio-version>/epinio-linux-amd64
MacOS
curl -o epinio -L https://github.com/epinio/epinio/releases/download/<epinio-version>/epinio-darwin-amd64
Windows
 curl -LO https://github.com/epinio/epinio/releases/download/<epinio-version>/epinio-windows-amd64.exe

Make the Binary Executable

For example on Linux and Mac:

chmod +x epinio

Move the binary to your PATH

sudo mv ./epinio /usr/local/bin/epinio

Verify the Installation

Run e.g. epinio version to test the successful installation.

> epinio version
Epinio Version: v0.1.0
Go Version: go1.17

Installation using a Custom Domain

For test and production environments. The installation will be done in three steps.

  • Install ingress in cluster
  • Configure your custom domain
  • Install Epinio in cluster

Install the Epinio CLI

If not done already, refer to Install the Epinio CLI.

Install Ingress In Cluster

First install ingress and wait for the loadbalancer-ip to be provisioned for the traefik public IP. Then map the loadbalancer-ip to your Domain Name e.g. test.example.com and wait for it to be mapped.

epinio install-ingress

The command prints the loadbalancer-ip ("EXTERNAL-IP") needed. Note however that it can also print a loadbalanced FQDN instead, which may resolve to multiple IPs.

Configure your custom DOMAIN

Currently we recommend to configure a wildcard domain for Epinio.

Given you own the domain "example.com", you would configure a subdomain e.g. "test.example.com" for Epinio. Now you will have to configure your DNS in a way, that any request towards "test.example.com" will resolve to the "EXTERNAL-IP" of Traefik, and Ingress will route the traffic accordingly.

  • test.example.com => "EXTERNAL-IP"
  • *.test.example.com => "EXTERNAL-IP"

Note you can also check the "EXTERNAL-IP" by running the command kubectl get svc -n traefik.

Find DNS Configuration Examples below.

Install Epinio In Cluster

With DNS now available the second step actually installs the cluster:

epinio install --system-domain test.example.com --tls-issuer=letsencrypt-production --use-internal-registry-node-port=false

Note: The issuer letsencrypt-production will work only, if your custom domain, e.g. "test.example.com", is reachable from the internet. For test, or internal environments, where your custom domain isn't reachable from the internet, you need to choose a different issuer. E.g. if you would use the custom domain "test.internal.com", epinio install --system-domain test.internal.com will default to the epinio-ca issuer.

DNS Configuration Examples

AWS EKS and Route53

As an example we will use the AWS Service Route53 to create a wildcard domain within one of your existing "Hosted zones", e.g. example.com.

Given Epinio ingress installation provided you with the following hostname:

Traefik Ingress info: [{"hostname":"abcdefg12345671234567abcdefg1234-1234567890.eu-west-1.elb.amazonaws.com"}]

Note you can also check the "EXTERNAL-IP"/FQDN by running the command kubectl get svc -n traefik.

Now you will have to add two CNAME records, for the subdomain, e.g. "test" to have "test.example.com", resp. "*.test.example.com". Replace "abcdefg12345671234567abcdefg1234-1234567890.eu-west-1.elb.amazonaws.com" with the your EKS FQDN, and "test.example.com" with your custom domain.

test.example.com
Record name: test
Record type: CNAME - Routes traffic to another domain name and some AWS resources
Value: abcdefg12345671234567abcdefg1234-1234567890.eu-west-1.elb.amazonaws.com
*.test.example.com
Record name: *.test
Record type: CNAME - Routes traffic to another domain name and some AWS resources
Value: abcdefg12345671234567abcdefg1234-1234567890.eu-west-1.elb.amazonaws.com

Finally, running

> host test.example.com, or even

> host epinio.test.example.com

should resolve to e.g. "abcdefg12345671234567abcdefg1234-1234567890.eu-west-1.elb.amazonaws.com".

Azure AKS and "example-domain"

As an example we will use the Azure resource group "example-domain", with the zone "example.com".

Given Epinio ingress installation provided you with the following hostname:

Traefik Ingress info: [{"ip":"10.0.0.1"}]

Note you can also check the "EXTERNAL-IP"/FQDN by running the command kubectl get svc -n traefik.

Now you will have to add two A records, for the subdomain, e.g. "test" to have "test.example.com", resp. "*.test.example.com" to the DNS zone "example.com". Replace "10.0.0.1" with the IP from "Traefik Ingress info", and "test.example.com" with your custom domain.

test.example.com
Record name: test.example.com
Record type: A
IP address: 10.0.0.1
*.test.example.com
Record name: *.test.example.com
Record type: A
IP address: 10.0.0.1

Finally, running

> host test.example.com, or even

> host epinio.test.example.com

should resolve to e.g. "10.0.0.1".

Bind DNS

Given Epinio ingress installation provided you with the following hostname:

Traefik Ingress info: [{"ip":"10.0.0.1"}]

Note you can also check the "EXTERNAL-IP"/FQDN by running the command kubectl get svc -n traefik.

Now you will have to add two A records, for the subdomain, e.g. "test" to have "test.example.com", resp. "*.test.example.com" to e.g. "/var/lib/named/master/forward/example.com". Replace "10.0.0.1" with the IP from "Traefik Ingress info", and "test.example.com" with your custom domain.

$ORIGIN example.com.
test			A	10.0.0.1
$ORIGIN test.example.com.
*			A	10.0.0.1

Restart bind and verify that e.g. > host test.example.com or > host epinio.test.example.com will resolve to "10.0.0.1".

Install Epinio using a Magic DNS Service

This is about just running epinio install. It should work on nearly any kubernetes distribution and provides you with a test environment. You will automatically get a magic wildcard domain like "10.0.0.1.omg.howdoi.website" which points to the public IP of Traefik.

Install the Epinio CLI

If not done already, refer to Install the Epinio CLI.

Install Epinio on the Cluster

epinio install

Troubleshooting

Traefik

In case of trouble with Epinio's Traefik component or Ingress controllers, the Traefik section in the Advanced Topics document shall be your friend.

DNS Rebind Protection

Some routers filter queries where the answer consists of IP addresses from the private range, like "10.0.0.1".

This stops a malicous website from probing the local network for hosts.

Amongst those routers is the AVM FRITZBox and everything that uses dnsmasq with stop-dns-rebind, like pfSense or NetworkManager.

If you still want to use the default magic DNS, you'll have to whitelist omg.howdoi.website in your local DNS server.

MS Azure AKS configuration

Create an AKS cluster

If you don't have an existing cluster, follow the quickstart to create an AKS cluster.

AKS Prerequisites

  • Epinio v0.1.0 has been tested with Azure AKS incl. kubernetes version v1.20.9
  • Epinio installation passed on a 2 node cluster with Standard_D3_v2 instances
  • To just try out Epinio, e.g. 2 Standard_D2_v2 are sufficient

Install

Beside advanced installation options, there are two ways of installing Epinio:

  1. Installation using a MagicDNS Service
  • For test environments. This should work on nearly any kubernetes distribution. Epinio will try to automatically create a magic DNS domain, e.g. 10.0.0.1.omg.howdoi.website.
  1. Installation using a Custom Domain
  • For test and production environments. You will define a system domain, e.g. test.example.com.

AWS EKS configuration

Create an EKS cluster

If you don't have an existing cluster, follow the quickstart to create an EKS cluster.

EKS Prerequisites

  • We follow the documented recommendation of having at least 2 nodes for EKS
  • Epinio v0.1.0 has been tested with AWS EKS incl. kubernetes version v1.20.7 and v1.21.2
  • To do more extensive testing we recommend a 2 node cluster with "t3.xlarge" instances
  • To just try out Epinio, e.g. 2 "t3a.large" are sufficient

Install

Installing Epinio in an EKS cluster is done in three steps.

Follow Installation using a Custom Domain for test and production environments.

Google GKE Configuration

Create a GKE cluster

Follow the quickstart to create a GKE cluster.

Install

Installing Epinio in an GKE cluster is done in three steps.

Follow Installation using a Custom Domain for test and production environments.

Troubleshooting

In case of trouble with Epinio's Traefik component or Ingress controllers, the Traefik section in the Advanced Topics document shall be your friend.

Rancher RKE2 configuration

Create an RKE2 cluster

If you don't have an existing cluster, follow the quickstart to create an RKE2 cluster.

RKE2 Prerequisites

  • A load-balancer is mandatory for Epinio to work on RKE2. Here MetalLB was used as load-balancer. See Provision of External IP for LoadBalancer service type in Kubernetes for more information.
  • Epinio v0.1.0 has been tested with Rancher RKE2 incl. kubernetes version v1.21.4+rke2r3
  • Epinio installation passed on a 3 node cluster (1 server, 2 agents) with Longhorn v1.1.1 storage class

Install

Beside advanced installation options, there are two ways of installing Epinio:

  1. Installation using a MagicDNS Service
  • For test environments. This should work on nearly any kubernetes distribution. Epinio will try to automatically create a magic DNS domain, e.g. 10.0.0.1.omg.howdoi.website.
  1. Installation using a Custom Domain
  • For test and production environments. You will define a system domain, e.g. test.example.com.

Creating a K3d Kubernetes Cluster

Get K3d Kubernetes Cluster

Install K3d

Follow the instructions to install k3d on your system.

Create a K3d kubernetes cluster

$ k3d cluster create epinio

Create a K3d kubernetes cluster when it is inside a VM

Epinio has to connect to pods inside the cluster. The default installation uses the internal docker IP for this. If docker is running in a VM, e.g. with Docker Desktop for Mac, that IP will not be reachable.

As a workaround the IP of the host can be used instead, together with port-forwardings:

k3d cluster create epinio -p '80:80@server[0]' -p '443:443@server[0]'

After the command returns, kubectl should already be talking to your new cluster:

$ kubectl get nodes
NAME                  STATUS   ROLES                  AGE   VERSION
k3d-epinio-server-0   Ready    control-plane,master   38s   v1.20.0+k3s2

Install Epinio on the Cluster

Follow Installation using a MagicDNS Service to install Epinio in your test environment.

If k3d is inside a VM, in addition to the special k3d setup, explained above, use this system domain instead:

epinio install --system-domain=<YOUR-IP>.omg.howdoi.website

<YOUR-IP> can be found by running

ifconfig |grep "inet.*broadcast

Troubleshooting

Kubeconfig

To get the kube config to access the cluster:

k3d kubeconfig get epinio

Traefik

In case of trouble with Epinio's Traefik component or Ingress controllers, the Traefik section in the Advanced Topics document shall be your friend.

Creating a K3s Kubernetes Cluster

Get K3s Kubernetes Cluster

Install K3s

Follow the instructions to install k3d on your system.

Install Epinio on the Cluster

Export the k3s cluster configration first:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Follow Installation using a MagicDNS Service to install Epinio in your test environment.

Troubleshooting

Traefik

In case of trouble with Epinio's Traefik component or Ingress controllers, the Traefik section in the Advanced Topics document shall be your friend.

Rancher Desktop configuration

Rancher Desktop Prerequisites

  • Running on Windows requires Windows Subsystem for Linux (WSL) which is automatically installed by Rancher Desktop

Install Rancher Desktop

Install the latest version from Rancher Desktop for your operating system

Setup Kubernetes

When running Rancher Desktop for the first time wait until the initialization is completed. Make sure that a supported Kubernetes version is selected under Kubernetes Settings, e.g. v1.21.5

Install epinio

Make sure Rancher Desktop is running.

Rancher Desktop can report Kubernetes as running while some pods are actually not yet ready. Manual verification is possible by executing the command kubectl get pods -A in a terminal and checking that all pods report either Running or Completed as their status.

Windows

  1. Start a terminal (e.g. type cmd in the search field) and change to the directory where epinio-windows-amd64 is located, e.g. cd Downloads

  2. Run epinio-windows-amd64 install

  3. Copy the binary to a directory of your choice and add it to the PATH variable as described by Kevin Berg's article. This allows execution of Epinio directly from any terminal.

Mac

  1. Start a terminal and change to the directory where epinio-darwin-amd64 is located, e.g. cd Downloads

  2. Run epinio-darwin-amd64 install

Linux

Linux is not yet supported by Rancher Desktop - see https://github.com/rancher-sandbox/rancher-desktop/issues/426

Creating a Minikube Kubernetes Cluster

Get Minikube Kubernetes Cluster

Install Minikube

Follow the instructions to install Minikube on your system.

Create a Minikube kubernetes cluster

Epinio installation was tested on Minikube with the following drivers: docker, kvm, virtualbox.

Specify the driver you want to use with the --driver option.

$ minikube start --driver=docker

Once the cluster is ready, you need to install the metallb addon:

$ minikube addons enable metallb

Then, you have to configure metallb by giving it an IP address range.
For instance check your minikube IP with minikube ip and choose how many IP addresses you need.

$ minikube ip
192.168.49.2

As an example, we choose the range 192.168.49.100-192.168.49.120.
Configure the addon with those values.

$ minikube addons configure metallb
-- Enter Load Balancer Start IP: 192.168.49.100
-- Enter Load Balancer End IP: 192.168.49.120
     Using image metallb/speaker:v0.9.6
     Using image metallb/controller:v0.9.6
  metallb was successfully configured

Now you can install Epinio on the Cluster.

Install Epinio on the Cluster

Follow Installation using a MagicDNS Service to install Epinio in your test environment.

Installing Wordpress with Epinio

Create a directory for your application:

mkdir wordpress
cd wordpress

Get the code:

https://wordpress.org/download/#download-install

wget https://wordpress.org/latest.tar.gz
tar xvf latest.tar.gz
mv wordpress htdocs
rm -rf latest.tar.gz

Create a buildpack.yml for your application

cat << EOF > buildpack.yml
---
php:
  version: 7.3.x
  script: index.php
  webserver: nginx
  webdirectory: htdocs
EOF

Enable needed php extensions

The PHP buildpack supports additional ini files for PHP through the PHP_INI_SCAN_DIR mechanism.

We need zlib and mysqli extensions enabled:

mkdir .php.ini.d
cat << EOF > .php.ini.d/extensions.ini
extension=zlib
extension=mysqli
EOF

Deploy

epinio push --name wordpress

Additional steps

Wordpress needs a database to work. After visiting the route of your deployed application you will have to set the connection details to the database.

You can install a MySQL database on your cluster or use an external one. One option is using a helm chart like this one: https://bitnami.com/stack/mysql/helm

Uninstall

NOTE: The command below will delete all the components Epinio originally installed. This includes all the deployed applications.

If after installing Epinio, you deployed other things on the same cluster that depended on those Epinio deployed components (e.g. Traefik, Tekton etc), then removing Epinio will remove those components and this may break your other workloads that depended on these. Make sure you understand the implications of uninstalling Epinio before you proceed.

If you want to completely uninstall Epinio from your kubernetes cluster, you can do this with the command:

epinio uninstall

Explanations

Documentation providing background information on key concepts.

Epinio, Advanced Topics

Contents

TODO: Do the same for Minio and list storage class requirements (WaitForFirstConsumer). Add links to upstream docs. TODO: Explain how to configure external S3 storage. TODO: Consider doing this in a separate document about the components. Or even, one document per components and links here.

Epinio installed components

Traefik

When you installed Epinio, it looked at your cluster to see if you had Traefik running. If it wasn't there it installed it.

As Epinio only checks two namespaces for Traefik's presence, namely traefik and kube-system, it is possible that it tries to install it, despite the cluster having Traefik running. Just in an unexpected place.

The install command provides the option --skip-traefik to handle this kind of situation.

Installing Epinio on your cluster with the command

$ epinio install --skip-traefik

forces Epinio to not install its own Traefik.

Note that having some other (non-Traefik) Ingress controller running is not a reason to prevent Epinio from installing Traefik. All the Ingresses used by Epinio expect to be handled by Traefik.

Also, the Traefik instance installed by Epinio, is configured to redirect all http requests to https automatically (e.g. the requests to the Epinio API, and the application routes). If you decide to use a Traefik instance which you deployed, you have to set this up yourself, Epinio won't change your Traefik installation in any way. Here are the relevant upstream docs for the redirection:

https://doc.traefik.io/traefik/routing/entrypoints/#redirection

Linkerd

By default, Epinio installs Linkerd on your cluster. The various namespaces created by Epinio become part of the Linkerd Service Mesh and thus all communication between pods is secured with mutualTLS.

In some cases you may not want Epinio to install Linkerd, either because you did that manually before you install Epinio or for other reasons. You can provide the --skip-linkerd flag to the install command to prevent Epinio from installing any of the Linkerd control plane components:

$ epinio install --skip-linkerd

Epinio

The epinio binary is used as:

  • a cli tool, used to push applications, create services etc.
  • the API server component which runs inside the cluster (invoked with the epinio server command)
  • the installer that installs the various needed components on the cluster. The API server from the previous point is one of them.

Epinio cli functionality is implemented using the endpoints provided by the Epinio API server component. For example, when the user asks Epinio to "push" an application, the cli will contact the "Upload", "Stage" and "Deploy" endpoints of the Epinio API to upload the application code, create a container image for the application using this code and run the application on the cluster.

The Epinio API server is running on the cluster and made accessible using Kubernetes resources like Deployments, Services, Ingresses and Secrets.

Cert Manager

Upstream documentation

The Cert manager component is deployed by Epinio and used to generate and renew the various Certificates needed in order to serve the various accessible endpoints over TLS (e.g. the Epinio API server).

Epinio supports various options when it comes to certificate issuers (let's encrypt, private CA, bring your own CA, self signed certs). Cert Manager simplifies the way we handle the various different certificate issuers within Epinio.

You can read more about certificate issuers here: certificate issuers documentation

Kubed

Upstream documentation

Kubed is installed by Epinio to keep secrets that are needed in more than one namespace synced. For example, the TLS certificate of the Container Registry is also needed in the Tekton staging namespace, in order to trust the certificate when pushing the application images.

Kubed makes sure that if the source secret changes, the copy will change too.

Warning: this doesn't mean things will still work if you re-generate a secret manually. Secret rotation will be handled by Epinio in the future.

Google Service Broker

Upstream project link

Many applications need additional services in order to work. Those services could be databases, cache servers, email gateways, log collecting applications or other. The various cloud providers already offer such services. Being able to use them in the various Platforms as a Service (PaaS) in a unified way gave birth to the concept of the (Open Service Broker API - aka osbapi)[https://www.openservicebrokerapi.org/]. This concept is adopted by various providers among which, Google. There seems to be a shift towards the "Operator" pattern, e.g. Google seems to have moved its focus to the Config Connector as described at the top of the README here.

Since Google's service broker still works and since the common interface provided by the Service Catalog makes it easy to integrate, Epinio lets the user optionally install the Google service broker with the command epinio enable services-google.

Warning: This service broker is not actively supported by Google anymore and may be removed from a future Epinio version.

Minibroker

Upstream project link

This is another implementation of the Open Service Broker API which can also be optionally be installed by epinio with the command epinio enable services-incluster.

Minibroker provisions services on the kubernetes cluster where Epinio is also running, using upstream helm charts. This can be useful for local development with Epinio, because it's fast and doesn't cost anything (services run locally).

Service Catalog

Upstream project link

The service catalog is the component that collects the various services provided by the various installed service brokers and presents them in a unified way to the user. The service catalog is the component behind the epinio service list-classes and epinio service list-plans commands.

Minio

Upstream project link

Minio is a storage solution that implements the same API as Amazon S3.

When the user pushes an application using a source code directory (with the epinio push command), the first step taken by the cli is to put the source code into a tarball and upload that to the Epinio API server. The server copies that to the configured S3 storage to be used later during the staging of the application.

When installing Epinio, the user can choose to use an external S3 compatible storage or let Epinio install Minio on the cluster (See here how).

Container Registry

The result of Epinio's application staging is a container image. This image is used to create a Kubernetes deployment to run the application code. The Tekton pipeline requires that image to be written to some container registry. Epinio installs a registry on the cluster itself to make the process easy and fast.

Note: In the future, Epinio may offer the option to use an external registry and not install one on the cluster (GitHub Issue).

Tekton

Pushing an application to Kubernetes with Epinio involves various steps. One of them is staging, which is the process that creates a container image out of the application source code using buildpacks. Epinio runs the staging process via a Tekton Pipeline.

Other Advanced Topics

Git Pushing

The quick way of pushing an application, as explained at Quickstart: Push an application, uses a local directory containing a checkout of the application's sources.

Internally this is actually quite complex. It involves the creation and upload of a tarball from these sources by the client to the Epinio server, copying into Epinio's internal (or external) S3 storage, copying from that storage to a PersistentVolumeClaim to be used in the tekton pipeline for staging, i.e. compilation and creation of the docker image to be used by the underlying kubernetes cluster.

The process is a bit different when using the Epinio client's "git mode". In this mode epinio push does not take a local directory of sources, but the location of a git repository holding the sources, and the id of the revision to use. The client then asks the Epinio server to pull those sources and store them to the S3 storage. The rest of the process is the same.

The syntax is

epinio push --name NAME --git GIT-REPOSITORY-URL,REVISION

For comparison all the relevant syntax:

epinio push
epinio push MANIFEST-PATH
epinio push --name NAME
epinio push --name NAME --path DIRECTORY
epinio push --name NAME --git GIT-REPOSITORY-URL,REVISION

Traefik and Linkerd

By default, with Epinio installing both Traefik and Linkerd, Epinio's installation process ensures that the Traefik pods are included in the Linkerd mesh, thus ensuring that external communication to applications is secured on the leg between loadbalancer and application service.

However, there are situations where Epinio does not install Traefik. This can be because the user specified --skip-traefik, or because Epinio detected a running Traefik, thus can forego its own. The latter is possible, for example, when using k3d as cluster foundation.

In these situations the pre-existing Traefik is not part of the Linkerd mesh. As a consequence the communication from loadbalancer to application service is not as secure.

While it is possible to fix this, the fix requires access to the cluster in general, and to Traefik's namespace specifically. In other words, permissions to annotate the Traefik namespace are needed, as well as permissions to restart the pods in that namespace. The latter is necessary, because Linkerd is not able to inject itself into running pods. It can only intercept pod (re)starts.

Example

Assuming that Traefik's namespace is called traefik, with pods traefik-6f9cbd9bd4-z4zw8 and svclb-traefik-q8g75 the commands

kubectl annotate namespace     traefik linkerd.io/inject=enabled
kubectl delete pod --namespace traefik traefik-6f9cbd9bd4-z4zw8 svclb-traefik-q8g75

will bring the Traefik in that namespace into Epinio's linkerd mesh.

Note that this recipe also works for a Traefik provided by k3d, in the kube-system namespace.

While it is the namespace which is annotated, only restarted pods are affected by that, i.e. Traefik's pods here. The other system pods continue to run as they are.

Epinio, CLI configuration

The Epinio command line client uses a configuration file to store information which has to persist across invocations. This document discusses various aspects around this.

Table Of Contents

Location

Epinio's configuration is located by default at ~/.config/epinio/config.yaml.

The location can be changed from command to command by specifying a different path with the global command line option --config-file.

A more permanent change is possible by setting the environment variable EPINIO_CONFIG to the desired path.

Contents

Epinio's configuration contains

  • The name of the namespace currently targeted.
  • Epinio API user name
  • Epinio API password
  • Epinio API urls (regular and websocket)
  • Epinio API certificate

The namespace can be changed by running epinio target with the name of the desired namespace as its single argument.

User name and password are used by the client to authenticate itself when talking to Epinio's API server. The epinio install command saves the initial information to the configuration.

The installation uses a the wildcard domain omg.howdoi.website and the epinio-ca issuer by default.

epinio install saves the associated CA certificate to the configuration so that future invocations of the client are able to verify the actual certificate when talking to Epinio's API server.

Commands

The Epinio command line client currently provides 3 commands explicitly targeting the configuration. These are:

  1. epinio target

    As noted in the previous section, this command changes the namespace to use with all other commands.

  2. epinio config show

    This command shows the details of the currently stored configuration settings. An exception is made for the certificate field, due to its expected size. The command's output only notes if certificate data is present or not.

  3. epinio config update

    Epinio allows users to switch between multiple installations (on different clusters) by simply re-targeting the cluster to talk to via changes to the environment variable KUBECONFIG.

    When such is done the credentials, cert data, and urls stored in the configuration will not match the newly targeted cluster, except by coincidence.

    To be actually able to talk to the newly targeted installation it is necessary to run this command to refresh the stored credentials, cert data, and urls with information retrieved from the new cluster.

Epinio Push in Detail

Epinio strives to make use of well supported, well known, and loved projects instead of re-inventing the wheel (link). But while doing so, it makes sure those components are deployed correctly and work together seamlessly. Let's go through the epinio push process in detail, so you can understand what each components does. You may also want to read the description of every component outside the push process here: Epinio components.

You can see an image that visualises the process later in this page. Refer to it while reading the text to help you understand the process more. The numbers on the various arrows on the image indicate the order of the various steps.

1. Epinio Push

Epinio exposes an API server running inside the kubernetes cluster for all clients including cli to talk to it. When you run the epinio push command, the first thing the cli is going to do, is to hit the relevant api endpoint for pushing apps. (1a) There is a Traefik ingress which sits in front of the Epinio API server which does BasicAuth for all the requests. (1b) After successful authentication, it routes the request to the Epinio API server. The cli puts your code inside a tarball and sends it to the upload endpoint of the Epinio API server which is running inside the Kubernetes cluster.

2. Copying the code to S3

One of the components Epinio installs on your cluster is Minio (unless you configured external S3). Minio is an S3 compatible storage solution. Epinio uses it to store the application's source code. It will later be used by the staging pipeline.

So the first thing the Epinio API server does when it receives the upload request (the previous step), is to store the source code tarball on S3.

3. Staging the App

When the upload request is complete, the cli will send a request to the stage endpoint of the Epinio API server. This will instruct the server to start the staging of the uploaded code.

4. Trigger the Pipeline

When the Epinio API server receives the stage request, it will create a PipelineRun that will run the staging Tekton pipeline using the version of the code referenced in the request. This pipeline has 3 steps. Their role is described in the following 3 sections.

5. Fetch the code

The first step of the staging Tekton pipeline downloads the code from the S3 storage to a workspace. This makes the code available to the following steps.

6. Stage

The second step of the staging Tekton pipeline uses the paketo buildpacks to create a container image for your application. The definition of this Tekton task can be found in the relevant upstream repo (though a copy of that is embedded in the Epinio binary). The result of a successful staging process is a new image pushed to the Registry component of Epinio.

This component is installed as part of the epinio install command and it is where the application images are stored. This makes the setup easier (by not having to configure an external registry) and staging faster (by keeping all image transferring local to the cluster). There is not much to tell about it but if you want to look at how the registry is installed, have a look at the helm chart here: https://github.com/epinio/epinio/tree/main/assets/container-registry/chart/container-registry

7. Run

To run a workload on Kubernetes having a container image is not enough. You need at least a Pod running with at least one container running that image.

The last step of the staging Tekton pipeline creates the runtime Kubernetes resources that are needed to make your application available to the users outside the Kubernetes cluster. The most important resources that are created are a Deployment, a Service and an Ingress resource.

8. Pull Image

The Deployment uses the image that was pushed as part of the staging step (see arrow 6). Now, the kubelet will pull the image from the registry for the deployment resource to use it.

You can read how these resources work in Kubernetes following the provided links but if you have to know one thing is that Ingress is the thing that describes how a request that uses the Application's url is routed to the application container. In Kubernetes, the thing that reads that description and implements the routing is called an Ingress Controller. Such an Ingress Controller is provided by Traefik.

Ingress Implementation (Traefik)

When you installed Epinio, it looked at your cluster to see if you had Traefik running. If it wasn't there it installed it. Traefik among other things, is an Ingress Controller. As explained above, the Ingress Controller reads your Ingress Resource Definitions and implements the desired routing to the appropriate Services/Pods.

In Epinio, for every application we create an Ingress that routes the traffic for this application through a subdomain that looks something like this:

myapplication.my_epinio_system_domain.com

You can get the route of your application with epinio apps list or epinio apps show myapplication

Additional Things

During installation, if you specified a system domain using the --system-domain parameter, then your application routes will be subdomains of that domain. Epinio considers this domain to be a production server and thus creates a production level TLS certificate for your application using Let's Encrypt. This is done by the cert-manager, which is one more of the components Epinio installs with epinio install.

If you didn't specify a system domain then Epinio uses a "magic DNS" service running on the omg.howdoi.website which is similar to nip.io, and xip.io. These services resolve all subdomains of the root domain to the subdomain's IP address. E.g. 1.2.3.4.omg.howdoi.website simply resolves to 1.2.3.4. They are useful when you don't have a real domain but you still need a wildcard domain to create subdomains for. Depending on your setup, the IP address of the cluster which Epinio discovers automatically may not be accessible by your browser and thus you may need to set the system domain when installing to use another IP. This is the case for example when you run a Kubernetes cluster with docker (e.g. k3d or kind) inside a VM (for example when using docker on Mac). Then the IP address which Epinio detects is the IP address of the docker container but that is not accessible from your host. You will need to bind the container's ports 80 and 443 to the VMs ports 80 and 443 and then use the VMs IP address instead.

The Process Visualized

epinio-push-detailed

Credits

  • Icons from: https://materialdesignicons.com/ (Source: https://github.com/Templarian/MaterialDesign)

Design Principles

Epinio's development is governed by the following principles:

  • Greater Developer Experience
    • Single command push for short learning curve
  • Edge Friendly
    • Has to fit in less than 4GB of RAM
  • Easy Installation
    • Has to install in less than 5 minutes when images are warm
    • Has to completely uninstall and leave the cluster in its previous state with a one-line command
  • Minimum Complexity
    • Scale from desktop/local to data center environment
    • Has to install with a one-line command and zero config
  • API Driven Architecture
  • Security Focused

Guidelines (Soft Principles)

  • When possible, prefer:
    • components that are written in go
    • Kubernetes primitives over custom resources
    • Well known components with active community over custom code
  • all acceptance tests should run in less than 10 minutes
  • all tests should be able to run on the minimal cluster

A Quick Note On Security

Epinio secures access to its API with TLS and basic authentication.

The installation process automatically creates and saves the necessary credentials (user, password) and certificates. The information is stored in Epinio's configuration, for pickup by other Epinio commands.

For a trial deployment the certificate securing the API will be generated by the underlying cluster, and self-signed, and its CA certificate is stored in the configuration to allow verification.

For a production-oriented deployment on the other hand, with a proper --system-domain specified, the certificate is obtained from Let's Encrypt instead. Nothing is stored in the configuration in that case, as Let's Encrypt is a known CA.

Epinio On Windows

Epinio relies on a number of command line tools which are normally available on any kind of Unix platform, yet rarely on Windows.

The general set contains

  • sh
  • sed
  • git

while the specific set consists of

  • kubectl
  • helm

We are currently recommending to install the Git For Windows distribution as it provides everything needed from the general set, and more.

For helm, kubectl, and epinio itself the necessary binaries can be retrieved from the relevant release pages or per their instructions:

HowTos

Documentation solving specific, sometimes advanced, problems in a practical manner.

Using a Certificate Issuer

Epinio comes with multiple cert-manager cluster issuers for creating certificates:

  • epinio-ca (default)
  • letsencrypt-production
  • selfsigned-issuer

The issuer will be used for both, the Epinio API endpoint and workloads (i.e. pushed applications).

Choosing a Different Issuer

When installing Epinio, one can choose between those issuers by using the --tls-issuer argument:

epinio install --tls-issuer=letsencrypt-production

Using a custom issuer

It's possible to create a cert-manager cluster issuer in the cluster, before installing Epinio and referencing it by name when installing.

However, this is only possible if the cert-manager CRD is present in the cluster.

We can use a split install, to install cert-manager first, then create the cluster issuer and finally install Epinio.

Split Install

Install cert-manager first:

epinio install-cert-manager

Then after creating the cluster issuer, install Epinio:

epinio install --skip-cert-manager

Cluster Issuer for ACME DNS Challenge

For example to use Letsencrypt with a DNS challenge, which supports wildcards and private IPs, create this cluster issuer after installing cert-manager:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: dns-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
    - dns01:
        cloudflare:
          email: user@example.com
          apiKeySecretRef:
            name: cloudflare-apikey-secret
            key: apikey
      selector:
        dnsNames:
        - 'example.com'
        - '*.example.com'

Note: This uses the Letsencrypt staging endpoint for testing. More information in the cert-manager ACME docs.

You can then install Epinio, without cert-manager, pointing to the new cluster issuer:

epinio install --skip-cert-manager --tls-issuer=dns-staging

Cluster Issuer for Existing Private CA

According to the instructions from https://cert-manager.io/docs/configuration/ca/, follow these steps:

Create Secret With CA Cert and Key

If you don't already have a private CA, use a tool like openssl or easy-rsa to create it.

The following oneliner creates a CA:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout example.key -out example.crt -subj "/CN=*.omg.howdoi.website"

Create a Kubernetes secret from the CA, in the cert-manager namespace.

kubectl create secret -n cert-manager tls private-ca-secret \
  --cert=./example.crt --key=./example.key

The cert-manager documentation has more details about this.

Create ClusterIssuer

Then create the cluster issuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: private-ca
spec:
  ca:
    secretName: private-ca-secret

Install Epinio

Use the --tls-issuer argument to choose your cluster issuer:

epinio install --skip-cert-manager --tls-issuer=private-ca

Use TLS When Pulling From Internal Registry

Epinio comes with its own registry for Docker images. This registry needs to be reachable from the Kubernetes nodes. If you are using a certificate issuer whose CA is trusted by the Kubernetes nodes, you can turn on SSL for pulling images from the internal registry:

epinio install --tls-issuer=letsencrypt-production --use-internal-registry-node-port=false

Without the node port, pushing images to the registry uses the "epinio-registry" ingress, which is handled by Traefik.

Background on Cert Manager and Issuers

Cert manager watches for a certificate resource and uses the referenced cluster issuer to generate a certificate. The certificate is stored in a secret, in the namespace the certificate resources was created in. An ingress resource can then use that secret to set up TLS.

Example:

  1. epinio install creates a certificate resource in epinio namespace
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
  name: epinio
  namespace: epinio
spec:
  commonName: epinio.172.27.0.2.omg.howdoi.website
  dnsNames:
  - epinio.172.27.0.2.omg.howdoi.website
  issuerRef:
    kind: ClusterIssuer
    name: epinio-ca
  secretName: epinio-tls
  1. cert-manager creates the 'epinio-tls' secret, using the referenced cluster issuer 'epinio-ca'
apiVersion: v1
kind: Secret
type: kubernetes.io/tls
metadata:
  annotations:
    cert-manager.io/alt-names: epinio.172.27.0.2.omg.howdoi.website
    cert-manager.io/certificate-name: epinio
    cert-manager.io/common-name: epinio.172.27.0.2.omg.howdoi.website
    cert-manager.io/ip-sans: ""
    cert-manager.io/issuer-group: ""
    cert-manager.io/issuer-kind: ClusterIssuer
    cert-manager.io/issuer-name: epinio-ca
    cert-manager.io/uri-sans: ""
  name: epinio-tls
  namespace: epinio
data:
  ca.crt: ...
  tls.crt: ...
  tls.key: ...
  1. Epinio creates an ingress resource
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: traefik
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.middlewares: epinio-epinio-api-auth@kubernetescrd
    traefik.ingress.kubernetes.io/router.tls: "true"
  labels:
    app.kubernetes.io/name: epinio
  name: epinio
  namespace: epinio
spec:
  rules:
  - host: epinio.172.27.0.2.omg.howdoi.website
    http:
      paths:
      - backend:
          service:
            name: epinio-server
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - epinio.172.27.0.2.omg.howdoi.website
    secretName: epinio-tls

Epinio Push

The same is true for applications, epinio push creates a certificate in the app's workspace and cert-manager creates a secret for the app's ingress.

Provision of External IP for LoadBalancer service type in Kubernetes

Local kubernetes platforms do not have the ability to provide external IP address when you create a kubernetes service with LoadBalancer service type. The following steps will enable this ability for different local kubernetes platforms. Follow these steps before installing epinio.

K3s/K3d

  • Provision of LoadBalancer IP is enabled by default in K3s/K3d.

Minikube

See Install Epinio on Minikube on how to configure minikube.

Kind

  • Install JQ from https://stedolan.github.io/jq/download/

  • Install and configure MetalLB

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.5/manifests/namespace.yaml
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.5/manifests/metallb.yaml
kubectl create secret generic -n metallb-system memberlist --from-literal=secretkey="$(openssl rand -base64 128)"

SUBNET_IP=`docker network inspect kind | jq -r '.[0].IPAM.Config[0].Gateway'`
## Use the last few IP addresses
IP_ARRAY=(${SUBNET_IP//./ })
SUBNET_IP="${IP_ARRAY[0]}.${IP_ARRAY[1]}.255.255"

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: metallb-system
  name: config
data:
  config: |
    address-pools:
    - name: default
      protocol: layer2
      addresses:
      - ${SUBNET_IP}/28
EOF

MicroK8s

  • Install and configure MetalLB
INTERFACE=`ip route | grep default | awk '{print $5}'`
IP=`ifconfig $INTERFACE | sed -n '2 p' | awk '{print $2}'`
microk8s enable metallb:${IP}/16

Digital Ocean

When installing Epinio on Rancher-provisioned RKE2 or RKE1 clusters on Digital Ocean, you might see this error message:

error installing Epinio:
timed out waiting for LoadBalancer IP on traefik service
Ensure your kubernetes platform has the ability to provision a LoadBalancer IP address.

In this case you need to configure RKE/RKE2 with an external cloud provider as this one.

One of the more interesting features of Rio was that it would let you set up a deployment that rebuilds and republishes when your code stored in Git is changed.

We can recreate this functionality using the GitJob CRD that's a part of Rancher Fleet.

NOTE: We will improve this experience in the future!

Setup

Install GitJob

If you don't have Rancher (or standalone Fleet) installed, we need to install the GitJob operator by following the instructions found at https://github.com/rancher/gitjob#running.

Then we need to setup the Service Account to run our Jobs with (since we don't need to do anything directly with the kube api, we don't need to add any role bindings to it):

apiVersion: v1
kind: ServiceAccount
metadata:
  name: epinio-push

Upload Epinio Config

So the GitJob can authenticate and push correctly, we can upload our Epinio config file to the cluster with:

kubectl create secret generic epinio-creds --from-file=$HOME/.config/epinio/config.yaml

This will create a secret containing the config.yaml that was created locally when you do epinio install or epinio config update

Setup Sample Project

Next, we can use the 12factor app to show how to write a GitJob.

Create a yaml file called 12factor-gitjob.yaml containing:

apiVersion: gitjob.cattle.io/v1
kind: GitJob
metadata:
  # The name of the GitJob, doesn't need to match the project.
  name: samplepush
spec:
  syncInterval: 15
  git:
    # The git repo and branch to track. 
    repo: https://github.com/epinio/example-12factor
    branch: main
  jobSpec:
    template:
      spec:
        # This should match what we created in the last step
        serviceAccountName: epinio-gitjob
        restartPolicy: "Never"
        containers:
        # This version should match your epinio deployment
        - image: "splatform/epinio-server:v0.1.0"
          name: epinio-push
          volumeMounts:
          - name: config
            mountPath: "/config/"
            readOnly: true
          env:
          - name: EPINIO_CONFIG
            value: "/config/config.yaml"
          command:
          - /epinio 
          args:
          - push 
          # This is the name of the app to push
          - test12factor
          workingDir: /workspace/source
        volumes:
        - name: config
          secret:
            secretName: epinio-creds

You can apply this via:

kubectl apply -f 12factor-gitjob.yaml

Once applied, you should see a Job and then Pod get created:

kubectl get job,pod

You can follow the logs of the pod listed above with:

kubectl logs <pod_name> -f

Using Webhooks

If you prefer to use webhooks instead of polling, set up the job in the same way as before but also follow the instructions found at: https://github.com/rancher/gitjob#webhook

How to setup external S3 storage

One of the steps involved in running epinio push is storing the requested version of the code in the configured Epinio S3 compatible storage. By default, Epinio installs and configures Minio to be used for this purpose. This document describes how to point Epinio to another S3 compatible storage and skip the Minio installation.

The epinio install command, has the following optional parameters:

--s3-endpoint
--s3-access-key-id
--s3-secret-access-key
--s3-bucket
--s3-location
--s3-use-ssl

To configure Epinio to store application sources to an external S3 compatible storage, at least the following should be set:

--s3-endpoint
--s3-access-key-id
--s3-secret-access-key
--s3-bucket

the other 2 are optional:

--s3-location
--s3-use-ssl

(Some implementations don't need the location (e.g. Minio) and s3-use-ssl has a default value of "false")

An example that points Epinio to AWS S3 will look like this:

epinio install \
--s3-endpoint s3.amazonaws.com \
--s3-access-key-id your_access_key_here \
--s3-secret-access-key your_secret_key_here \
--s3-bucket epinio_sources \
--s3-location eu-central-1
--s3-use-ssl

If the bucket doesn't exist, Epinio will try to create it when it first tries to write to it. Make sure the access key and the access secret have enough permissions to create a bucket and then write to it.

When you successfully push a new version of your application, Epinio will remove the resources of the previous staging process from the Kubernetes cluster and will also delete the previous version of the sources from S3. This way, Epinio doesn't store more than it needs on the S3 storage and the user doesn't need to manually cleanup.

Reference documentation

For example all CLI commands and their arguments.

ServerAdminUser
componentAPIInstallationCLI
needs(kubeconfig)kubeconfigkubeconfigconfig file
commandsserverinstallconfig updateinfo
install-traefiknamespace
install-cert-managertarget
enablepush
disableconfig show|colors

Command reference


title: "epinio" linkTitle: "epinio" weight: 1

epinio

Epinio cli

Synopsis

epinio cli is the official command line interface for Epinio PaaS

Options

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -h, --help                     help for epinio
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app" linkTitle: "epinio app" weight: 1

epinio app

Epinio application features

Synopsis

Manage epinio application

epinio app [flags]

Options

  -h, --help   help for app

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app create" linkTitle: "epinio app create" weight: 1

epinio app create

Create just the app, without creating a workload

epinio app create NAME [flags]

Options

  -b, --bind strings      services to bind immediately
  -e, --env strings       environment variables to be used
  -h, --help              help for create
  -i, --instances int32   The number of instances the application should have (default 1)

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app delete" linkTitle: "epinio app delete" weight: 1

epinio app delete

Deletes an application

epinio app delete NAME [flags]

Options

  -h, --help   help for delete

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app env" linkTitle: "epinio app env" weight: 1

epinio app env

Epinio application configuration

Synopsis

Manage epinio application environment variables

epinio app env [flags]

Options

  -h, --help   help for env

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app env list" linkTitle: "epinio app env list" weight: 1

epinio app env list

Lists application environment

Synopsis

Lists environment variables of named application

epinio app env list APPNAME [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app env set" linkTitle: "epinio app env set" weight: 1

epinio app env set

Extend application environment

Synopsis

Add or change environment variable of named application

epinio app env set APPNAME NAME VALUE [flags]

Options

  -h, --help   help for set

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app env show" linkTitle: "epinio app env show" weight: 1

epinio app env show

Describe application's environment variable

epinio app env show APPNAME NAME [flags]

Options

  -h, --help   help for show

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app env unset" linkTitle: "epinio app env unset" weight: 1

epinio app env unset

Shrink application environment

Synopsis

Remove environment variable from named application

epinio app env unset APPNAME NAME [flags]

Options

  -h, --help   help for unset

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app list" linkTitle: "epinio app list" weight: 1

epinio app list

Lists applications

Synopsis

Lists applications in the targeted namespace, or all

epinio app list [--all] [flags]

Options

      --all    list all applications
  -h, --help   help for list

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app logs" linkTitle: "epinio app logs" weight: 1

epinio app logs

Streams the logs of the application

epinio app logs NAME [flags]

Options

      --follow    follow the logs of the application
  -h, --help      help for logs
      --staging   show the staging logs of the application

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app manifest" linkTitle: "epinio app manifest" weight: 1

epinio app manifest

Save state of the named application as a manifest

epinio app manifest NAME MANIFESTPATH [flags]

Options

  -h, --help   help for manifest

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app show" linkTitle: "epinio app show" weight: 1

epinio app show

Describe the named application

epinio app show NAME [flags]

Options

  -h, --help   help for show

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio app update" linkTitle: "epinio app update" weight: 1

epinio app update

Update the named application

Synopsis

Update the running application's attributes (e.g. instances)

epinio app update NAME [flags]

Options

  -b, --bind strings      services to bind immediately
  -e, --env strings       environment variables to be used
  -h, --help              help for update
  -i, --instances int32   The number of instances the application should have (default 1)

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio config" linkTitle: "epinio config" weight: 1

epinio config

Epinio config management

Synopsis

Manage the epinio cli configuration

epinio config [flags]

Options

  -h, --help   help for config

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio config colors" linkTitle: "epinio config colors" weight: 1

epinio config colors

Manage colored output

Synopsis

Enable/Disable colored output

epinio config colors BOOL [flags]

Options

  -h, --help   help for colors

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio config show" linkTitle: "epinio config show" weight: 1

epinio config show

Show the current configuration

epinio config show [flags]

Options

  -h, --help   help for show

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio config update" linkTitle: "epinio config update" weight: 1

epinio config update

Update the api location & stored credentials

Synopsis

Update the api location and stored credentials from the current cluster

epinio config update [flags]

Options

  -h, --help   help for update

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio info" linkTitle: "epinio info" weight: 1

epinio info

Shows information about the Epinio environment

Synopsis

Shows status and versions for epinio's server-side components.

epinio info [flags]

Options

  -h, --help   help for info

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio install-cert-manager" linkTitle: "epinio install-cert-manager" weight: 1

epinio install-cert-manager

install Epinio's cert-manager in your configured kubernetes cluster

Synopsis

install Epinio cert-manager controller in your configured kubernetes cluster

epinio install-cert-manager [flags]

Options

      --email-address string   The email address you are planning to use for getting notifications about your certificates (default "epinio@suse.com")
  -h, --help                   help for install-cert-manager
  -i, --interactive            Whether to ask the user or not (default not)

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio install-ingress" linkTitle: "epinio install-ingress" weight: 1

epinio install-ingress

install Epinio's Ingress in your configured kubernetes cluster

Synopsis

install Epinio Ingress controller in your configured kubernetes cluster

epinio install-ingress [flags]

Options

  -h, --help                     help for install-ingress
  -i, --interactive              Whether to ask the user or not (default not)
      --loadbalancer-ip string   IP address to be assigned to ingress loadbalancer service
      --skip-linkerd             Assert to epinio that Linkerd is already installed.

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio install" linkTitle: "epinio install" weight: 1

epinio install

install Epinio in your configured kubernetes cluster

Synopsis

install Epinio PaaS in your configured kubernetes cluster

epinio install [flags]

Options

      --email-address string              The email address you are planning to use for getting notifications about your certificates (default "epinio@suse.com")
  -h, --help                              help for install
  -i, --interactive                       Whether to ask the user or not (default not)
      --loadbalancer-ip string            IP address to be assigned to ingress loadbalancer service
      --password string                   The password for authenticating all API requests
      --s3-access-key-id string           If you are using your own S3 compatible object storage for blobs, set the access key id with this setting.
      --s3-bucket string                  If you are using your own S3 compatible object storage for blobs, set the bucket with this setting.
      --s3-endpoint string                If you are using your own S3 compatible object storage for blobs, set the S3 endpoint with this setting.
      --s3-location string                If you are using your own S3 compatible object storage for blobs, set the S3 bucket location with this setting.
      --s3-secret-access-key string       If you are using your own S3 compatible object storage for blobs, set the secret access key with this setting.
      --s3-use-ssl                        If you are using your own S3 compatible object storage for blobs, toggle SSL on or off.
      --skip-cert-manager                 Assert to epinio that cert-manager is already installed.
  -s, --skip-default-namespace            Set this to skip the creation of a default namespace
      --skip-linkerd                      Assert to epinio that Linkerd is already installed.
      --skip-traefik                      Assert to epinio that there is a Traefik active, even if epinio cannot find it.
      --system-domain string              The domain you are planning to use for Epinio. Should be pointing to the traefik public IP (Leave empty to use a omg.howdoi.website domain).
      --tls-issuer string                 The name of the cluster issuer to use. Epinio creates three options: 'epinio-ca', 'letsencrypt-production', and 'selfsigned-issuer'. (default "epinio-ca")
      --use-internal-registry-node-port   Make the internal registry accessible via a node port, so kubelet can access the registry without trusting its cert. (default true)
      --user string                       The user name for authenticating all API requests

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio namespace" linkTitle: "epinio namespace" weight: 1

epinio namespace

Epinio-controlled namespaces

Synopsis

Manage epinio-controlled namespaces

epinio namespace [flags]

Options

  -h, --help   help for namespace

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio namespace create" linkTitle: "epinio namespace create" weight: 1

epinio namespace create

Creates an epinio-controlled namespace

epinio namespace create NAME [flags]

Options

  -h, --help   help for create

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio namespace delete" linkTitle: "epinio namespace delete" weight: 1

epinio namespace delete

Deletes an epinio-controlled namespace

epinio namespace delete NAME [flags]

Options

  -f, --force   force namespace deletion
  -h, --help    help for delete

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio namespace list" linkTitle: "epinio namespace list" weight: 1

epinio namespace list

Lists all epinio-controlled namespaces

epinio namespace list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio namespace show" linkTitle: "epinio namespace show" weight: 1

epinio namespace show

Shows the details of an epinio-controlled namespace

epinio namespace show NAME [flags]

Options

  -h, --help   help for show

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio push" linkTitle: "epinio push" weight: 1

epinio push

Push an application declared in the specified manifest

epinio push [flags] [PATH_TO_APPLICATION_MANIFEST]

Options

  -b, --bind strings                 services to bind immediately
      --builder-image string         Paketo builder image to use for staging
      --container-image-url string   Container image url for the app workload image
  -e, --env strings                  environment variables to be used
  -g, --git string                   Git repository and revision of sources separated by comma (e.g. GIT_URL,REVISION)
  -h, --help                         help for push
  -i, --instances int32              The number of instances the application should have (default 1)
  -n, --name string                  Application name. (mandatory if no manifest is provided)
  -p, --path string                  Path to application sources.

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio server" linkTitle: "epinio server" weight: 1

epinio server

Starts the Epinio server.

Synopsis

This command starts the Epinio server. epinio install ensures the server is running inside your cluster. Normally you don't need to run this command manually.

epinio server [flags]

Options

  -h, --help                              help for server
      --port int                          (PORT) The port to listen on. Leave empty to auto-assign a random port
      --tls-issuer string                 (TLS_ISSUER) The cluster issuer to use for workload certificates (default "epinio-ca")
      --use-internal-registry-node-port   (USE_INTERNAL_REGISTRY_NODE_PORT) Use the internal registry via a node port (default true)

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service" linkTitle: "epinio service" weight: 1

epinio service

Epinio service features

Synopsis

Handle service features with Epinio

epinio service [flags]

Options

  -h, --help   help for service

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service bind" linkTitle: "epinio service bind" weight: 1

epinio service bind

Bind a service to an application

Synopsis

Bind service by name, to named application.

epinio service bind NAME APP [flags]

Options

  -h, --help   help for bind

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service create" linkTitle: "epinio service create" weight: 1

epinio service create

Create a service

Synopsis

Create service by name and key/value dictionary.

epinio service create NAME (KEY VALUE)... [flags]

Options

  -h, --help   help for create

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service delete" linkTitle: "epinio service delete" weight: 1

epinio service delete

Delete a service

Synopsis

Delete service by name.

epinio service delete NAME [flags]

Options

  -h, --help     help for delete
      --unbind   Unbind from applications before deleting

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service list" linkTitle: "epinio service list" weight: 1

epinio service list

Lists all services

epinio service list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service show" linkTitle: "epinio service show" weight: 1

epinio service show

Service information

Synopsis

Show detailed information of the named service.

epinio service show NAME [flags]

Options

  -h, --help   help for show

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio service unbind" linkTitle: "epinio service unbind" weight: 1

epinio service unbind

Unbind service from an application

Synopsis

Unbind service by name, from named application.

epinio service unbind NAME APP [flags]

Options

  -h, --help   help for unbind

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio target" linkTitle: "epinio target" weight: 1

epinio target

Targets an epinio-controlled namespace.

epinio target [namespace] [flags]

Options

  -h, --help   help for target

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio uninstall" linkTitle: "epinio uninstall" weight: 1

epinio uninstall

uninstall Epinio from your configured kubernetes cluster

Synopsis

uninstall Epinio PaaS from your configured kubernetes cluster

epinio uninstall [flags]

Options

  -h, --help   help for uninstall

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO


title: "epinio version" linkTitle: "epinio version" weight: 1

epinio version

Print the version number

epinio version [flags]

Options

  -h, --help   help for version

Options inherited from parent commands

      --config-file string       (EPINIO_CONFIG) set path of configuration file (default "~/.config/epinio/config.yaml")
  -c, --kubeconfig string        (KUBECONFIG) path to a kubeconfig, not required in-cluster
      --no-colors                Suppress colorized output
      --skip-ssl-verification    (SKIP_SSL_VERIFICATION) Skip the verification of TLS certificates
      --timeout-multiplier int   (EPINIO_TIMEOUT_MULTIPLIER) Multiply timeouts by this factor (default 1)
      --trace-level int          (TRACE_LEVEL) Only print trace messages at or above this level (0 to 5, default 0, print nothing)
      --verbosity int            (VERBOSITY) Only print progress messages at or above this level (0 or 1, default 0)

SEE ALSO

Epinio supported applications

This section describes what kind of application you can expect to work with Epinio. To understand what enables an application to work with Epinio, you need to know how staging works.

How it works

Epinio relies on Cloud Native Buildpacks to create a container image for your application. It does that by installing and using the upstream maintained Tekton pipelines.

Staging starts with you (the developer) running epinio push --name myapp from the root of your application source code. You can see a simplified diagram of the process in the image below:

epinio-push-simplified

After pushing your code, Epinio triggers a Tekton pipeline which uses the paketo buildpacks to build a runtime image for your application. If you are not familiar with how buildpacks work, you should have a look at the official docs: https://buildpacks.io/docs/

Supported buildpacks

Epinio uses the full stack paketo builder image which means you can make use of any of the buildpacks documented here: https://paketo.io/docs/buildpacks/language-family-buildpacks/

The various buildpacks provide various configuration options. You can read on how to generally configure a buildpack here: https://paketo.io/docs/buildpacks/configuration/ Each buildpack may support more configuration options, so you may have to read the documentation of the buildpacks you are interested in.

E.g. Instructions on how to add custom php.ini files for php-web buildpack

Detailed push process

The above image is a simplified explanation of the epinio push process. If you don't want to know all the details on how that works, the above diagram should be all the information you need. If you are curious about the details, then read here: Detailed push docs

Application Manifests

Overview

An application manifest is a YAML file containing the entire configuration of an application as required by epinio (apps) push for succesful operation.

Manifests are irrelevant for all other epinio commands.

This is especially true for the commands epinio apps create and epinio apps update. Neither of these uses manifests. They operate directly on a named application, and can only set and modify a subset of the data provided by a manifest to epinio (apps) push.

Cheat Sheet

The detailed specifications coming after this section provide the following essential ways of pushing an application:

  1. With an explicit manifest file as argument.

  2. With a standard manifest file (epinio.yml) found in the current directory.

  3. With no manifest file at all. This simply uses all the defaults, except for the name, which has no such.

Further defaults:

  • No environment variables.
  • No bound services.
  • One replica/instance.
  • Standard paketo builder image (paketobuildpacks/builder:full).
  • Current directory for the application sources.

Syntax epinio (apps) push

Outside of options epinio (apps) push supports only a single optional argument. This argument is the path to the manifest file to use.

When no such path is specified the command looks for an epinio.yml file in the current directory as the manifest to use.

When no manifest file is found defaults are applied.

Syntax:

  • push [flags] [MANIFEST-PATH]

The command does support a number of options with which the user can override the information read from the manifest. In other words, the data in the manifest is the primary source, and the options just tweak things.

When an option is specified its value replaces the data from the manifest. Options do not extend any manifest values.

Options

  • --instances, -i N

    The application's number of desired instances/replicas.

  • --env, -e NAME=VALUE

    Adds the environment variable NAME to the application's environment, with the specified VALUE. Multiple uses of the option accumulate. In case of multiple assignments to the same NAME the last wins.

  • --bind, -b SERVICE

    Binds the named service to the application. Multiple uses of the option accumulate.

Side note: The three preceding options are supported by the apps create and apps update commands as well. The following options are not.

  • --name, -n NAME

    The application's name. When used more than once the last use wins.

The next three options specify the location of the application's sources. Only one form is allowed. Mixing forms causes push to report an error.

  • --path, -p SRC-PATH

    A path in the local filesystem, the directory holding the application's sources. When used more than once the last use wins.

    A relative path is resolved relative to the current working directory.

  • --container-image, -c URL

    The url of the container image containing the ready-to-run application. In other words, this is a pre-staged application, not sources. When used more than once the last use wins.

  • --git, -g REPO?,REV?

    The url of the git repository holding the appliction's sources, and the revision to use. If the revision is not specified the head of the main branch is assumed. When used more than once the last use wins.

    Note: The comma (,) is used as separator between repo url and revision because the nicer separators (:, @) are both used in urls, making extraction difficult due to the ambiguities coming out of that.

The last option controls staging:

  • --builder-image IMAGE

    The name of the image to use for staging the application's sources.

Manifest format

An application manifest is a YAML file containing a single mapping as its main structure.

The keys of this mapping specify the various elements of an application's configuration.

  • name. See --name. Required.

  • configuration. Optional. The value of this key is a mapping whose keys specify the basic configuration of the application, namely:

    • instances. See --instances. Optional. Defaults to 1.

    • environment. See --env. Optional. Defaults to empty. The value of this key is a mapping whose keys are the names of the desired environment variables, and their desired values.

    • services. See --bind. Optional. Defaults to empty. The value of this keys is a sequence of names, for the services to bind.

  • staging. Optional. The value of this key is a mapping whose keys specify information controlling the application's staging.

    • builder. See --builder-image. Optional.
  • origin. Optional. The value of this key is a mapping whose keys specify the origin of the application (sources), namely:

    • path. See --path. Optional. See below.

      A relative path is resolved relative to the directory containing the manifest file.

    • container. See --container-image. Optional. See below.

    • git. See --git. Optional. See below. The value of this key is a mapping with keys url and revision, for the two part of the git reference. If revision is not present it defaults to the head of the repositories' main branch.

    As with the options the keys path, container, and git exclude each other. Only one may be specified in the manifest.

    If none is specified the system defaults to path and the sources are expected to reside in the directory containing the manifest file.

    Note that specifying any of the origin options replaces any of the origin keys. I.e. a --path options replaces/displace/overides a container key. Etc.

Last, in case it was missed reading the descriptions above, name is the only required key in a manifest file. The same as the NAME argument of pre-manifest push was the only required argument.

Example

name: zanzibar
configuration:
  instances: 333
  services:
  - snafu
  environment:
    DOGMA: "no"
staging:
  builder: "paketobuildpacks/builder:tiny"
origin:
  path: /somewhere/over/there

Services

Overview

Services are, in general, external components providing some kind of service (sic!) to applications, without being a direct part of the applications.

Examples of services are

  • databases,
  • message brokers,
  • interfaces to other kinds of systems,
  • etc.

In Epinio services are identified by a name and the namespace they are defined in. Beyond that they consist of a collection of arbitrarily named attributes and values, which when consumed by an application, tell that aplication how to connect to and interact with that service.

Note that while there are guidelines what kind of attributes are required for the above, and how they should be named, and what their content should be, these guidelines are outside of the scope for Epinio. Epinio is not aware of such, and cannot validate service definition against such. It will simply pass any attributes to using applications as they are, and assumes that they are what the application requires for proper function.

For an application to use a service, the service has to be bound to the application. In other words, the application has to be made aware of the service.

Note how this constrains the lifetimes of services with respect to applications. A service is expected to exist before a using application exists, and to only be deleted after all using applications are gone.

Deleting a service used by an application is considered an error and generally prevented. While it can be forced it should then be expected to break the application.

As a limitation, applications can only bind services defined in the same namespace as the application itself.

Management

Services in Epinio are managed by the epinio service command hierarchy.

The connections between services and applications specifically are managed by the bind and unbind commands.

Application Interface

From the point of view of an epinio-staged application, a bound service appears in the application's file system as a directory under the path /services. This directory will have the same name as the service and will contain a set of files holding the attributes of the service. Each attribute is mapped to a file of the same name as the attribute, and this file contains the value of the attribute.

Example

To be a bit more concrete, let us assume that we have a service created by the command epinio service create orders host over-there port 99 user zetta password 92084dkls.

When an application binds that service several additional paths will appear in the filesystem of that application, namely:

|Path |Kind |Content | |--- |--- |--- | |/services/orders |Directory | | |/services/orders/host |File |over-there | |/services/orders/port |File |99 | |/services/orders/user |File |zetta | |/services/orders/password |File |92084dkls |

The application can now read these files and use their content to connect to the service, authenticate, and then use it.