diff --git a/charts/workflow/values.yaml b/charts/workflow/values.yaml index addd34e2..18b4df99 100644 --- a/charts/workflow/values.yaml +++ b/charts/workflow/values.yaml @@ -51,6 +51,12 @@ global: host_port: 5555 # Prefix for the imagepull secret created when using private registry secret_prefix: "private-registry" + # Experimental feature to use Kubernetes ingress instead of Workflow's deis-router. + # + # Valid values are: + # - true: deis-router will not be deployed. Workflow will not be usable until a Kubernetes ingress controller is installed. + # - false: deis-router will be deployed (default). + experimental_native_ingress: false s3: @@ -107,6 +113,10 @@ controller: # disabled - turns off open registration # admin_only - allows for registration by an admin only. registration_mode: "admin_only" + # The publicly resolvable hostname to build your cluster with. + # + # This will be the hostname that is used to build endpoints such as "deis.$HOSTNAME" + platform_domain: "" database: # The username and password to be used by the on-cluster database. 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..6ca5bae7 --- /dev/null +++ b/src/installing-workflow/experimental-native-ingress.md @@ -0,0 +1,81 @@ +# 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 global.experimental_native_ingress=true,controller.platform_domain=deis.com +``` + +Where `controller.platform_domain` is a **required** parameter that is traditionally not required for Workflow that is explained in the next section. 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 several Kubernetes ingresses 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 waiting for minio 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.experimental_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 `*.$host` record to the public IP address of your ingress controller. You can get the public IP using the following command. A wildcard entry is necessary here as apps will use the same rule after they are deployed. + +``` +$ 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). + +##### Feedback + +While this feature is experimental we welcome feedback on the issue. We would like to learn more about use cases, and user experience. Please [open a new issue](https://github.com/deis/workflow/issues/new) for feedback. diff --git a/src/installing-workflow/index.md b/src/installing-workflow/index.md index 5e0fa005..fcf6ba83 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) to take advantage of native Kubernetes routing. Any compatible Kubernetes ingress controller can be used in place of Workflow's nginx-based deis-router. Follow [this guide](experimental-native-ingress.md) to enable experimental native ingress. + ## 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..d9dfbe11 100644 --- a/src/quickstart/deploy-an-app.md +++ b/src/quickstart/deploy-an-app.md @@ -1,18 +1,36 @@ -## 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`. -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`. +#### Option 1: Standard Installation + +For a standard installation that includes deis-router, you can calculate the hostname value using its public IP address and a wildcard DNS record. + +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 workflow requires a wildcard DNS record to dynamically map app names to the router. + +#### Option 2: Experimental Native Ingress Installation -Use the controller url to register a user in the cluster. +In this example, the user should already have DNS set up pointing to their known host. The `$hostname` value can be calculated by prepending `deis.` to the value set in `controller.platform_domain`. + +**$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 +38,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,7 +68,7 @@ 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 ```