From 2692d6691dade8d510b032dd68f093449d8d8efb Mon Sep 17 00:00:00 2001 From: Kris Nova Date: Thu, 2 Mar 2017 14:19:10 -0700 Subject: [PATCH] feat(ingress): Experimental Native Ingress Adding documentation changes for Kubernetes ingress support. Non breaking change, as users must opt-in to the feature. --- charts/workflow/values.yaml | 10 +++ mkdocs.yml | 1 + .../experimental-native-ingress.md | 80 +++++++++++++++++++ src/installing-workflow/index.md | 4 + src/quickstart/deploy-an-app.md | 38 +++++++-- 5 files changed, 125 insertions(+), 8 deletions(-) create mode 100644 src/installing-workflow/experimental-native-ingress.md diff --git a/charts/workflow/values.yaml b/charts/workflow/values.yaml index addd34e2..d55ee2c2 100644 --- a/charts/workflow/values.yaml +++ b/charts/workflow/values.yaml @@ -51,6 +51,16 @@ global: host_port: 5555 # Prefix for the imagepull secret created when using private registry secret_prefix: "private-registry" + # The public resolvable hostname to build your cluster with. + # + # This will be the hostname that is used to build endpoints such as "deis.$HOSTNAME" + hostname: "" + # Experimental feature to toggle using kubernetes ingress instead of the Deis router. + # + # Valid values are: + # - true: The Deis router will NOT be deployed. Inherently workflow will not be usable until a Kubernetes ingress controller is installed. + # - false: The default mode, and the default behavior of Deis workflow. + experimental_native_ingress: false s3: diff --git a/mkdocs.yml b/mkdocs.yml index cb61aec3..01f99911 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,6 +37,7 @@ pages: - Configuring Postgres: installing-workflow/configuring-postgres.md - Configuring the Registry: installing-workflow/configuring-registry.md - Chart Provenance: installing-workflow/chart-provenance.md + - Experimental Native Ingress: installing-workflow/experimental-native-ingress.md - Users: - Command Line Interface: users/cli.md - Users and Registration: users/registration.md diff --git a/src/installing-workflow/experimental-native-ingress.md b/src/installing-workflow/experimental-native-ingress.md new file mode 100644 index 00000000..f7b34051 --- /dev/null +++ b/src/installing-workflow/experimental-native-ingress.md @@ -0,0 +1,80 @@ +# Experimental Native Ingress + +## Install Deis Workflow (With experimental native ingress support) + +Now that Helm is installed and the repository has been added, install Workflow with a native ingress by running: + +``` +$ helm install deis/workflow --namespace deis --set experimental_native_ingress=true,global.hostname="deis.com" +``` + +Where `global.hostname` is a **required** parameter that is traditionally not required for Workflow. In this example we are using `deis.com` for `$hostname`. + + + +Helm will install a variety of Kubernetes resources in the `deis` namespace. +Wait for the pods that Helm launched to be ready. Monitor their status by running: + +``` +$ kubectl --namespace=deis get pods +``` + +You should also notice that a Kubernetes ingress has been installed on your cluster. You can view it by running: + +``` +$ kubectl get ingress --namespace deis +``` + + +Depending on the order in which the Workflow components initialize, some pods may restart. This is common during the +installation: if a component's dependencies are not yet available, that component will exit and Kubernetes will +automatically restart it. + +Here, it can be seen that the controller, builder and registry all took a few loops before they were able to start: + +``` +$ kubectl --namespace=deis get pods +NAME READY STATUS RESTARTS AGE +deis-builder-hy3xv 1/1 Running 5 5m +deis-controller-g3cu8 1/1 Running 5 5m +deis-database-rad1o 1/1 Running 0 5m +deis-logger-fluentd-1v8uk 1/1 Running 0 5m +deis-logger-fluentd-esm60 1/1 Running 0 5m +deis-logger-sm8b3 1/1 Running 0 5m +deis-minio-4ww3t 1/1 Running 0 5m +deis-registry-asozo 1/1 Running 1 5m +deis-workflow-manager-68nu6 1/1 Running 0 5m +``` + +## Install a Kubernetes Ingress Controller + +Now that Workflow has been deployed with the `global.exerpimental_native_ingress` flag set to `true`, we will need a Kubernetes ingress controller in place to begin routing traffic. + +Here is an example of how to use [traefik](https://traefik.io/) as an ingress controller for Workflow. Of course, you are welcome to use any controller you wish. + +``` +$ helm install stable/traefik --name deis-ingress-001 --namespace kube-system +``` + +## Configure DNS + +The experimental ingress feature requires a user to set up a hostname, and assumes the `deis.$host` convention. + +We need to point the `deis.$host` record to the public IP address of your ingress controller. You can get the public IP using the following command. + +``` +$ kubectl get svc deis-ingress-001 --namespace kube-system +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +deis-ingress-001 10.23.253.220 104.154.159.184 80:30231/TCP,443:32264/TCP 19m +``` + +If we were using `deis.com` as a hostname we would need to create the following A DNS record. + +| Name | Type | Value | +| ----------------- |:-------------:| ---------------:| +| deis.deis.com | A | 104.154.159.184 | + + +Once all of the pods are in the `READY` state, and `deis.$host` resolves to the external IP found above Workflow is up an running! + +After installing Workflow, [register a user and deploy an application](../quickstart/deploy-an-app.md). diff --git a/src/installing-workflow/index.md b/src/installing-workflow/index.md index 5e0fa005..17bd5eef 100644 --- a/src/installing-workflow/index.md +++ b/src/installing-workflow/index.md @@ -33,6 +33,10 @@ More rigorous installations would benefit from using outside sources for the fol * [Redis](../managing-workflow/platform-logging.md#configuring-off-cluster-redis) - Such as AWS Elasticache * [InfluxDB](../managing-workflow/platform-monitoring.md#configuring-off-cluster-influxdb) and [Grafana](../managing-workflow/platform-monitoring.md#off-cluster-grafana) +#### (Experimental) Kubernetes Native Ingress + +Workflow now offers [experimental native ingress](experimental-native-ingress.md) that will allow users to take advantage of native Kubernetes ingress with their cluster. Users will be able to use and define any compatible Kubernetes ingress controller. Feel free to start following along with the [experimental native ingress](experimental-native-ingress.md) guide now. + ## Add the Deis Chart Repository The Deis Chart Repository contains everything needed to install Deis Workflow onto a Kubernetes cluster, with a single `helm install deis/workflow --namespace deis` command. diff --git a/src/quickstart/deploy-an-app.md b/src/quickstart/deploy-an-app.md index 9a94fdbf..24e8d1f5 100644 --- a/src/quickstart/deploy-an-app.md +++ b/src/quickstart/deploy-an-app.md @@ -1,18 +1,38 @@ -## Register an Admin User +## Determine your host and hostname values -The first user to register against Deis Workflow will automatically be given administrative privileges. +For the rest of this example we will refer to a special variables called `$hostname`. Please choose one of the two methods for building your `$hostname`. + +#### Option 1: Standard Installation -If you installed Deis on GKE or AWS, Deis automatically creates a load balancer for the cluster. To get the IP of this load balancer, run `kubectl --namespace=deis describe svc deis-router`. +For a standard installation you can build the hostname using public IP address and a wildcard DNS solution. Instead of setting up DNS records, this example will use `nip.io`. + +If your router IP is `1.1.1.1`, its `$hostname` will be `1.1.1.1.nip.io`. You can find your IP address by running: + +``` +kubectl --namespace=deis describe svc deis-router +``` If you do not have an load balancer IP, the router automatically forwards traffic from a kubernetes node to the router. In this case, use the IP of a kubernetes node and the node port that routes to port 80 on the controller. -Deis requires a wildcard DNS record to dynamically map app names to the router. Instead of setting up DNS records, this example will use `nip.io`. If your router IP is `1.1.1.1`, its url will be `1.1.1.1.nip.io`. The URL of the controller component will be `deis.1.1.1.1.nip.io`. +Deis requires a wildcard DNS record to dynamically map app names to the router. + +**$hostname**: 1.1.1.1.nip.io + +#### Option 2: Experimental Native Ingress Installation + +In this example, the user should already have DNS set up pointing to their known host. The `$hostname` value can be build by appending `deis.` to the value set in `global.exerpimental_native_ingress`. -Use the controller url to register a user in the cluster. +**$hostname**: deis.com + +## Register an Admin User + +The first user to register against Deis Workflow will automatically be given administrative privileges. + +Use the controller `$hostname` to register a user in the cluster. ``` -$ deis register http://deis.104.197.125.75.nip.io +$ deis register http://$hostname username: admin password: password (confirm): @@ -20,7 +40,7 @@ email: jhansen@deis.com Registered admin Logged in as admin $ deis whoami -You are admin at http://deis.104.197.125.75.nip.io +You are admin at http://$hostname ``` You have now registered your first user and you are ready to deploy an application. @@ -50,10 +70,12 @@ Let's use the CLI to tell the platform to deploy an application and then use cur ``` $ deis pull deis/example-go -a proper-barbecue Creating build... done -$ curl http://proper-barbecue.104.197.125.75.nip.io +$ curl http://proper-barbecue.$hostname Powered by Deis ``` + + !!! note If you see a 404 error, make sure you specified your application name with `-a `!