From 059e5e2ec5184a6876a47c257d9d55e72bc05fe8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 18 Apr 2018 10:44:22 -0400 Subject: [PATCH 001/311] add skeleton --- src/en/caas.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 src/en/caas.md diff --git a/src/en/caas.md b/src/en/caas.md new file mode 100644 index 000000000..0c01eed1b --- /dev/null +++ b/src/en/caas.md @@ -0,0 +1,28 @@ +Title: CAAS + +# CAAS + +CAAS is *Containers As A Service*. + +"k8s" +Kubernetes upstream + +## Getting started + + +## Architecture + + +## Charms + + +## Configuration + + +## Commands + + +## Credentials + + +## Storage From e871e76fb675afbbb8b2e657665a7f1c10447505 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 18 Apr 2018 17:00:13 -0400 Subject: [PATCH 002/311] add definitions and installation information --- src/en/caas.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 84 insertions(+), 5 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index 0c01eed1b..abb1623c2 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -1,14 +1,85 @@ Title: CAAS +TODO: Once 2.4 is officially released remove support Note and update status output # CAAS CAAS is *Containers As A Service*. -"k8s" -Kubernetes upstream - -## Getting started - +Kubernetes (often abbreviated as "k8s") provides a flexible architecture for +managing containerised applications at scale (see the +[Kubernetes documentation][upstream-kubernetes-docs] for more information). + +!!! Important: + Juju provides base Kubernetes support starting with version 2.4-beta1. + +## Using Kubernetes with Juju + +First off, a Kubernetes cluster will be required. Essentially, you will use it +as you would any other cloud that Juju interacts with: the cluster becomes the +backing cloud. In this document, we deploy the cluster using Juju itself. + +To deploy a minimal two-machine Kubernetes cluster we'll use the +[kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: + +```bash +juju deploy kubernetes-core +``` + +!!! Note: + An alternative to using the bundle is to use the `conjure-up` installer. + See Ubuntu tutorial + [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up]. + Although it specifically mentions the + [Canonical Distribution of Kubernetes][cdk-charm] you can choose the + identical minimal install deployed above from the tool's interface. + +Sample output (here on the localhost cloud) looks like this: + +```no-highlight +Model Controller Cloud/Region Version SLA +default lxd-caas localhost/localhost 2.4-beta1 unsupported + +App Version Status Scale Charm Store Rev OS Notes +easyrsa 3.0.1 active 1 easyrsa jujucharms 39 ubuntu +etcd 2.3.8 active 1 etcd jujucharms 77 ubuntu +flannel 0.9.1 active 2 flannel jujucharms 52 ubuntu +kubernetes-master 1.10.0 waiting 1 kubernetes-master jujucharms 102 ubuntu exposed +kubernetes-worker 1.10.0 active 1 kubernetes-worker jujucharms 114 ubuntu exposed + +Unit Workload Agent Machine Public address Ports Message +easyrsa/0* active idle 0/lxd/0 10.0.45.195 Certificate Authority connected. +etcd/0* active idle 0 10.40.174.204 2379/tcp Healthy with 1 known peer +kubernetes-master/0* waiting idle 0 10.40.174.204 6443/tcp Waiting for kube-system pods to start + flannel/0* active idle 10.40.174.204 Flannel subnet 10.1.53.1/24 +kubernetes-worker/0* active idle 1 10.40.174.193 80/tcp,443/tcp Kubernetes worker running. + flannel/1 active idle 10.40.174.193 Flannel subnet 10.1.25.1/24 + +Machine State DNS Inst id Series AZ Message +0 started 10.40.174.204 juju-562a96-0 xenial Running +0/lxd/0 started 10.0.45.195 juju-562a96-0-lxd-0 xenial Container started +1 started 10.40.174.193 juju-562a96-1 xenial Running + +Relation provider Requirer Interface Type Message +easyrsa:client etcd:certificates tls-certificates regular +easyrsa:client kubernetes-master:certificates tls-certificates regular +easyrsa:client kubernetes-worker:certificates tls-certificates regular +etcd:cluster etcd:cluster etcd peer +etcd:db flannel:etcd etcd regular +etcd:db kubernetes-master:etcd etcd regular +kubernetes-master:cni flannel:cni kubernetes-cni subordinate +kubernetes-master:kube-api-endpoint kubernetes-worker:kube-api-endpoint http regular +kubernetes-master:kube-control kubernetes-worker:kube-control kube-control regular +kubernetes-worker:cni flannel:cni kubernetes-cni subordinate +``` + +Copy the main configuration file from the Kubernetes master node: + +```bash +mkdir ~/.kube +juju scp kubernetes-master/0:config ~/.kube/config +``` + +The contents of this file will be used in a subsequent command. ## Architecture @@ -26,3 +97,11 @@ Kubernetes upstream ## Storage + + + + +[kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ +[ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 +[cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ +[upstream-kubernetes-docs]: https://kubernetes.io/docs From a95d8c9adde2fb6a6a46817f753181d25740ff6a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 19 Apr 2018 15:47:03 -0400 Subject: [PATCH 003/311] fill in the empty spaces --- src/en/caas.md | 58 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index abb1623c2..ffaefad61 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -1,13 +1,17 @@ -Title: CAAS +Title: CAAS and Juju TODO: Once 2.4 is officially released remove support Note and update status output -# CAAS +# CAAS and Juju -CAAS is *Containers As A Service*. +CAAS is *Containers as a Service*, a cloud service that allows users to upload, +organize, run, scale, manage, and stop containers. Combining this with Juju +opens up a new vista of possibilities for Juju users. Currently, Juju supports +Kubernetes as its underlying CAAS solution. Kubernetes (often abbreviated as "k8s") provides a flexible architecture for managing containerised applications at scale (see the -[Kubernetes documentation][upstream-kubernetes-docs] for more information). +[Kubernetes documentation][upstream-kubernetes-docs] for more information). It +most commonly employs Docker as its container technology. !!! Important: Juju provides base Kubernetes support starting with version 2.4-beta1. @@ -16,9 +20,19 @@ managing containerised applications at scale (see the First off, a Kubernetes cluster will be required. Essentially, you will use it as you would any other cloud that Juju interacts with: the cluster becomes the -backing cloud. In this document, we deploy the cluster using Juju itself. +backing cloud. -To deploy a minimal two-machine Kubernetes cluster we'll use the +To summarise, the steps for using Kubernetes with Juju are: + + 1. Obtain a cluster + 1. Add the cluster to Juju + 1. Deploy CAAS-specific charms + +### Obtain a Kubernetes cluster + +You may obtain a Kubernetes cluster in any way. However, in this document, we +deploy the cluster using Juju itself. We will do so by deploying a minimal +two-machine Kubernetes cluster by making use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash @@ -29,7 +43,7 @@ juju deploy kubernetes-core An alternative to using the bundle is to use the `conjure-up` installer. See Ubuntu tutorial [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up]. - Although it specifically mentions the + for guidance. Although the tutorial specifically mentions the [Canonical Distribution of Kubernetes][cdk-charm] you can choose the identical minimal install deployed above from the tool's interface. @@ -72,14 +86,38 @@ kubernetes-master:kube-control kubernetes-worker:kube-control kube-c kubernetes-worker:cni flannel:cni kubernetes-cni subordinate ``` -Copy the main configuration file from the Kubernetes master node: +### Add the cluster to Juju + +We will need some information about the cluster in order to add it to Juju. +This is found within the main Kubernetes configuration file. + +!!! Note: + If `conjure-up` was used to install the cluster then the rest of this + section can be skipped; this install method adds the cluster for you. + +#### Adding quickly (bundle installs) + +If the `juju deploy` command was used to deploy the cluster the above file can +be copied over from the Kubernetes master node (and saved as `~/.kube/config`) +in this way: ```bash mkdir ~/.kube juju scp kubernetes-master/0:config ~/.kube/config ``` - -The contents of this file will be used in a subsequent command. + +We can now take advantage of the `add-k8s` command as it internally parses the +copied configuration file from the specified path. This allows us to quickly +add the cluster-cloud, which we arbitrarily have called 'k8cloud': + +```bash +juju add-k8s k8cloud +``` + +#### Adding manually (third-party installs) + +`add-cloud` +`add-credential` ## Architecture From 07de86152ea307cd33935758d0295a9adee8d9af Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 25 Apr 2018 13:45:14 -0400 Subject: [PATCH 004/311] add credentials and configuration sections; some rewording elsewhere --- src/en/caas.md | 82 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 14 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index ffaefad61..94eaeac3b 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -1,11 +1,12 @@ Title: CAAS and Juju TODO: Once 2.4 is officially released remove support Note and update status output + Should eventually link to CAAS-charm developer documentation # CAAS and Juju CAAS is *Containers as a Service*, a cloud service that allows users to upload, organize, run, scale, manage, and stop containers. Combining this with Juju -opens up a new vista of possibilities for Juju users. Currently, Juju supports +opens up new practical benefits for Juju users. Currently, Juju supports Kubernetes as its underlying CAAS solution. Kubernetes (often abbreviated as "k8s") provides a flexible architecture for @@ -13,8 +14,33 @@ managing containerised applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. -!!! Important: - Juju provides base Kubernetes support starting with version 2.4-beta1. +## CAAS-specific workflow + +Here we discuss how a Juju workflow and be different in a CAAS environment. + +### Commands + +The only CAAS-specific Juju command is `add-k8s`. All other commands can be +used, such as `add-unit` for scaling purposes. + +### Credentials + +Credentials work the same way as for any other backing cloud (see +[Credentials][credentials]). However, when `juju add-k8s` is run immediately +after deploying a k8s bundle, the contents of file `~/.kube/config` are +imported into Juju. This file contains the IP endpoint address of the master +Kubernetes node, a CA certificate, and user credentials. + +User credentials can still be added by way of the `add-credential` +or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used +to add a new user to the k8s cluster. + +The `add-k8s` command can be used repeatedly to set up different clusters as +long as the contents of the configuration file has been changed accordingly. +The KUBECONFIG environment variable is useful here as it will be honoured by +Juju when finding the file to load. + +We'll demonstrate the use of the `add-k8s` command below. ## Using Kubernetes with Juju @@ -27,7 +53,7 @@ To summarise, the steps for using Kubernetes with Juju are: 1. Obtain a cluster 1. Add the cluster to Juju 1. Deploy CAAS-specific charms - + ### Obtain a Kubernetes cluster You may obtain a Kubernetes cluster in any way. However, in this document, we @@ -108,7 +134,7 @@ juju scp kubernetes-master/0:config ~/.kube/config We can now take advantage of the `add-k8s` command as it internally parses the copied configuration file from the specified path. This allows us to quickly -add the cluster-cloud, which we arbitrarily have called 'k8cloud': +add the cluster-cloud, which we have arbitrarily called 'k8cloud': ```bash juju add-k8s k8cloud @@ -122,17 +148,44 @@ juju add-k8s k8cloud ## Architecture -## Charms - - ## Configuration - -## Commands - - -## Credentials - +Juju CAAS applications support application specific configuration. This allows +k8s configuration to be used to control how Juju deploys the application on +Kubernetes. The following are supported (these names are the Juju configuration +attribute names; the k8s meaning should be obvious): + +| Key | Type | Default | Valid values | Comments | +|:----------------------------------------------|---------|------------------|--------------|:-----------------------------| +kubernetes-service-type | string | ClusterIP | | +kubernetes-service-external-ips | string | [] | | +kubernetes-service-target-port | string | | | +kubernetes-service-loadbalancer-ip | string | "" | | +kubernetes-service-loadbalancer-sourceranges | string | [] | | +kubernetes-service-externalname | string | "" | | +kubernetes-ingress-class | string | nginx | | +kubernetes-ingress-ssl-redirect | boolean | false | | +kubernetes-ingress-ssl-passthrough | boolean | false | | +kubernetes-ingress-allow-http | boolean | false | | + +There are three other configuration attributes which are not k8s-specific: + +| Key | Type | Default | Valid values | Comments | +|:----------------------------------------------|---------|------------------|--------------|:-----------------------------| +juju-managed-units | boolean | false | | +juju-external-hostname | string | | | Mandatory; user specified +juju-application-path | string | "/" | | + +Attributes 'juju-external-hostname' and 'juju-application-path' control how the +application is exposed externally using a Kubernetes Ingress Resource in +conjunction with the configured ingress controller (default: nginx). + +Attribute 'juju-managed-units' is used to control whether Juju manages the +lifecyle of the pods, or whether that is delegated to a deployment controller. +In the latter case, Juju itself can be used to add or remove units as normal. +But it's also possible to use the k8s scale command outside of Juju to add or +remove pods directly in k8s and these changes will be reflected back into the +Juju model as updates to units. ## Storage @@ -143,3 +196,4 @@ juju add-k8s k8cloud [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [upstream-kubernetes-docs]: https://kubernetes.io/docs +[credentials]: ./credentials.html From 438a964d425ab6e3b396747da6e4812a38abe45b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 25 Apr 2018 13:53:45 -0400 Subject: [PATCH 005/311] trivial --- src/en/caas.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index 94eaeac3b..c3a3ed58d 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -16,7 +16,8 @@ most commonly employs Docker as its container technology. ## CAAS-specific workflow -Here we discuss how a Juju workflow and be different in a CAAS environment. +Here we discuss how a standard Juju workflow may be different in a CAAS +environment. ### Commands @@ -183,7 +184,7 @@ conjunction with the configured ingress controller (default: nginx). Attribute 'juju-managed-units' is used to control whether Juju manages the lifecyle of the pods, or whether that is delegated to a deployment controller. In the latter case, Juju itself can be used to add or remove units as normal. -But it's also possible to use the k8s scale command outside of Juju to add or +It's also possible to use the k8s `scale` command (external to Juju) to add or remove pods directly in k8s and these changes will be reflected back into the Juju model as updates to units. From 93e70fa3b291aa39cbf110ea090353f62646774e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 27 Apr 2018 12:19:21 -0400 Subject: [PATCH 006/311] rejig opening sections --- src/en/caas.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index c3a3ed58d..aa51b8cee 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -16,21 +16,17 @@ most commonly employs Docker as its container technology. ## CAAS-specific workflow -Here we discuss how a standard Juju workflow may be different in a CAAS -environment. +Here we discuss how a building and working with a CAAS environment may differ +from a standard Juju workflow. -### Commands +The only CAAS-specific Juju command is `add-k8s`, which acts as the `add-cloud` +command for Kubernetes clouds/clusters. All other concepts and commands are +applied in the traditional Juju manner. -The only CAAS-specific Juju command is `add-k8s`. All other commands can be -used, such as `add-unit` for scaling purposes. - -### Credentials - -Credentials work the same way as for any other backing cloud (see -[Credentials][credentials]). However, when `juju add-k8s` is run immediately -after deploying a k8s bundle, the contents of file `~/.kube/config` are -imported into Juju. This file contains the IP endpoint address of the master -Kubernetes node, a CA certificate, and user credentials. +If the Kubernetes cluster is built with Juju itself (via a bundle) and `juju +add-k8s` is run immediately afterwards, the contents of file `~/.kube/config` +(if it exists) are used to add the cluster and the credentials to Juju, making +commands `add-cloud` and `add-credential` unnecessary. User credentials can still be added by way of the `add-credential` or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used @@ -42,7 +38,7 @@ The KUBECONFIG environment variable is useful here as it will be honoured by Juju when finding the file to load. We'll demonstrate the use of the `add-k8s` command below. - + ## Using Kubernetes with Juju First off, a Kubernetes cluster will be required. Essentially, you will use it @@ -53,16 +49,18 @@ To summarise, the steps for using Kubernetes with Juju are: 1. Obtain a cluster 1. Add the cluster to Juju + 1. Create a controller (and optionally a model) 1. Deploy CAAS-specific charms - + ### Obtain a Kubernetes cluster You may obtain a Kubernetes cluster in any way. However, in this document, we -deploy the cluster using Juju itself. We will do so by deploying a minimal -two-machine Kubernetes cluster by making use of the +deploy the cluster using Juju itself (with the localhost cloud). We will do so +by deploying a minimal two-machine Kubernetes cluster by making use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash +juju bootstrap localhost lxd-caas juju deploy kubernetes-core ``` @@ -74,7 +72,7 @@ juju deploy kubernetes-core [Canonical Distribution of Kubernetes][cdk-charm] you can choose the identical minimal install deployed above from the tool's interface. -Sample output (here on the localhost cloud) looks like this: +Sample output looks like this: ```no-highlight Model Controller Cloud/Region Version SLA From 3029eafabfe1339d8c7fa818fa64a15459d01738 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 7 May 2018 12:45:55 -0400 Subject: [PATCH 007/311] remove some items until stabalised --- src/en/caas.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index aa51b8cee..9ba77eeda 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -1,6 +1,9 @@ Title: CAAS and Juju TODO: Once 2.4 is officially released remove support Note and update status output Should eventually link to CAAS-charm developer documentation + Update when storage becomes a Juju drivable aspect. + Add architectural overview/diagram once CAAS becomes stable. + Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` # CAAS and Juju @@ -139,14 +142,6 @@ add the cluster-cloud, which we have arbitrarily called 'k8cloud': juju add-k8s k8cloud ``` -#### Adding manually (third-party installs) - -`add-cloud` -`add-credential` - -## Architecture - - ## Configuration Juju CAAS applications support application specific configuration. This allows @@ -171,7 +166,6 @@ There are three other configuration attributes which are not k8s-specific: | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| -juju-managed-units | boolean | false | | juju-external-hostname | string | | | Mandatory; user specified juju-application-path | string | "/" | | @@ -179,14 +173,10 @@ Attributes 'juju-external-hostname' and 'juju-application-path' control how the application is exposed externally using a Kubernetes Ingress Resource in conjunction with the configured ingress controller (default: nginx). -Attribute 'juju-managed-units' is used to control whether Juju manages the -lifecyle of the pods, or whether that is delegated to a deployment controller. -In the latter case, Juju itself can be used to add or remove units as normal. -It's also possible to use the k8s `scale` command (external to Juju) to add or -remove pods directly in k8s and these changes will be reflected back into the -Juju model as updates to units. - -## Storage +Juju uses a deployment controller for each application to manage pod lifecycle, +which allows for the addition or removal of units as normal. It remains +possible to perform these same actions directly in the cluster by way of the +Kubernetes `scale` command. From 9bc8d19e9efc798eef56e73eeea65083f11b383f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 8 May 2018 10:29:56 -0400 Subject: [PATCH 008/311] trivial --- src/en/caas.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/en/caas.md b/src/en/caas.md index 9ba77eeda..1e41767dc 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -178,6 +178,10 @@ which allows for the addition or removal of units as normal. It remains possible to perform these same actions directly in the cluster by way of the Kubernetes `scale` command. +## Charms + + + From 53e19196d00073587c29219fc4cd457f39d0ab33 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 22 May 2018 13:16:38 -0400 Subject: [PATCH 009/311] add remove-k8s command --- src/en/caas.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index 1e41767dc..98fb11a4a 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -22,14 +22,13 @@ most commonly employs Docker as its container technology. Here we discuss how a building and working with a CAAS environment may differ from a standard Juju workflow. -The only CAAS-specific Juju command is `add-k8s`, which acts as the `add-cloud` -command for Kubernetes clouds/clusters. All other concepts and commands are -applied in the traditional Juju manner. +The only CAAS-specific Juju commands are `add-k8s` and `remove-k8s`. All other +concepts and commands are applied in the traditional Juju manner. If the Kubernetes cluster is built with Juju itself (via a bundle) and `juju add-k8s` is run immediately afterwards, the contents of file `~/.kube/config` (if it exists) are used to add the cluster and the credentials to Juju, making -commands `add-cloud` and `add-credential` unnecessary. +the usual combination of `add-cloud` and `add-credential` unnecessary. User credentials can still be added by way of the `add-credential` or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used From 4b73326e5f5caf3916aa5fa531d1f71ca0966039 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 23 May 2018 12:59:21 -0400 Subject: [PATCH 010/311] update status output --- src/en/caas.md | 58 ++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 33 deletions(-) diff --git a/src/en/caas.md b/src/en/caas.md index 98fb11a4a..c1eca7c41 100644 --- a/src/en/caas.md +++ b/src/en/caas.md @@ -25,10 +25,11 @@ from a standard Juju workflow. The only CAAS-specific Juju commands are `add-k8s` and `remove-k8s`. All other concepts and commands are applied in the traditional Juju manner. -If the Kubernetes cluster is built with Juju itself (via a bundle) and `juju -add-k8s` is run immediately afterwards, the contents of file `~/.kube/config` -(if it exists) are used to add the cluster and the credentials to Juju, making -the usual combination of `add-cloud` and `add-credential` unnecessary. +If the Kubernetes cluster is built with Juju itself (via a bundle) and +`juju add-k8s` is run immediately afterwards, the contents of file +`~/.kube/config` (if it exists) is used to add the cluster and the credentials +to Juju, making the usual combination of `add-cloud` and `add-credential` +unnecessary. User credentials can still be added by way of the `add-credential` or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used @@ -78,39 +79,30 @@ Sample output looks like this: ```no-highlight Model Controller Cloud/Region Version SLA -default lxd-caas localhost/localhost 2.4-beta1 unsupported +default lxd localhost/localhost 2.4-beta3 unsupported App Version Status Scale Charm Store Rev OS Notes -easyrsa 3.0.1 active 1 easyrsa jujucharms 39 ubuntu -etcd 2.3.8 active 1 etcd jujucharms 77 ubuntu -flannel 0.9.1 active 2 flannel jujucharms 52 ubuntu -kubernetes-master 1.10.0 waiting 1 kubernetes-master jujucharms 102 ubuntu exposed -kubernetes-worker 1.10.0 active 1 kubernetes-worker jujucharms 114 ubuntu exposed - -Unit Workload Agent Machine Public address Ports Message -easyrsa/0* active idle 0/lxd/0 10.0.45.195 Certificate Authority connected. -etcd/0* active idle 0 10.40.174.204 2379/tcp Healthy with 1 known peer -kubernetes-master/0* waiting idle 0 10.40.174.204 6443/tcp Waiting for kube-system pods to start - flannel/0* active idle 10.40.174.204 Flannel subnet 10.1.53.1/24 -kubernetes-worker/0* active idle 1 10.40.174.193 80/tcp,443/tcp Kubernetes worker running. - flannel/1 active idle 10.40.174.193 Flannel subnet 10.1.25.1/24 +easyrsa 3.0.1 active 1 easyrsa jujucharms 40 ubuntu +etcd 3.2.9 active 1 etcd jujucharms 80 ubuntu +flannel 0.9.1 active 2 flannel jujucharms 56 ubuntu +kubernetes-master 1.10.2 waiting 1 kubernetes-master jujucharms 104 ubuntu exposed +kubernetes-worker 1.10.2 active 1 kubernetes-worker jujucharms 118 ubuntu exposed + +Unit Workload Agent Machine Public address Ports Message +easyrsa/0* active idle 0/lxd/0 10.0.219.187 Certificate Authority connected. +etcd/0* active idle 0 10.191.96.169 2379/tcp Healthy with 1 known peer +kubernetes-master/0* waiting executing 0 10.191.96.169 6443/tcp (config-changed) Waiting for kube-system pods to start + flannel/0* active idle 10.191.96.169 Flannel subnet 10.1.21.1/24 +kubernetes-worker/0* active executing 1 10.191.96.126 80/tcp,443/tcp (config-changed) Kubernetes worker running. + flannel/1 active idle 10.191.96.126 Flannel subnet 10.1.69.1/24 Machine State DNS Inst id Series AZ Message -0 started 10.40.174.204 juju-562a96-0 xenial Running -0/lxd/0 started 10.0.45.195 juju-562a96-0-lxd-0 xenial Container started -1 started 10.40.174.193 juju-562a96-1 xenial Running - -Relation provider Requirer Interface Type Message -easyrsa:client etcd:certificates tls-certificates regular -easyrsa:client kubernetes-master:certificates tls-certificates regular -easyrsa:client kubernetes-worker:certificates tls-certificates regular -etcd:cluster etcd:cluster etcd peer -etcd:db flannel:etcd etcd regular -etcd:db kubernetes-master:etcd etcd regular -kubernetes-master:cni flannel:cni kubernetes-cni subordinate -kubernetes-master:kube-api-endpoint kubernetes-worker:kube-api-endpoint http regular -kubernetes-master:kube-control kubernetes-worker:kube-control kube-control regular -kubernetes-worker:cni flannel:cni kubernetes-cni subordinate +0 started 10.191.96.169 juju-c841ac-0 xenial Running +0/lxd/0 started 10.0.219.187 juju-c841ac-0-lxd-0 xenial Container started +1 started 10.191.96.126 juju-c841ac-1 xenial Running + +Controller Timestamp +23 May 2018 14:00:52Z ``` ### Add the cluster to Juju From 2656eed287fe6a6d60c1ca7d7024e39ece1164e1 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 21 Jun 2018 09:28:09 -0400 Subject: [PATCH 011/311] terminology; TODO --- src/en/{caas.md => clouds-k8s.md} | 40 +++++++++++++------------------ 1 file changed, 16 insertions(+), 24 deletions(-) rename src/en/{caas.md => clouds-k8s.md} (88%) diff --git a/src/en/caas.md b/src/en/clouds-k8s.md similarity index 88% rename from src/en/caas.md rename to src/en/clouds-k8s.md index c1eca7c41..1b22c5aa1 100644 --- a/src/en/caas.md +++ b/src/en/clouds-k8s.md @@ -1,28 +1,24 @@ -Title: CAAS and Juju +Title: Using Kubernetes with Juju TODO: Once 2.4 is officially released remove support Note and update status output - Should eventually link to CAAS-charm developer documentation + Should eventually link to k8s-charm developer documentation Update when storage becomes a Juju drivable aspect. - Add architectural overview/diagram once CAAS becomes stable. + Add architectural overview/diagram once Juju:k8s becomes stable. Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` + Add charms section when they become available in the charm store -# CAAS and Juju - -CAAS is *Containers as a Service*, a cloud service that allows users to upload, -organize, run, scale, manage, and stop containers. Combining this with Juju -opens up new practical benefits for Juju users. Currently, Juju supports -Kubernetes as its underlying CAAS solution. +# Using Kubernetes with Juju Kubernetes (often abbreviated as "k8s") provides a flexible architecture for managing containerised applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. -## CAAS-specific workflow +## Juju k8s-specific workflow -Here we discuss how a building and working with a CAAS environment may differ -from a standard Juju workflow. +Here we discuss how building and working with a k8s environment may differ from +a standard Juju workflow. -The only CAAS-specific Juju commands are `add-k8s` and `remove-k8s`. All other +The only k8s-specific Juju commands are `add-k8s` and `remove-k8s`. All other concepts and commands are applied in the traditional Juju manner. If the Kubernetes cluster is built with Juju itself (via a bundle) and @@ -31,9 +27,9 @@ If the Kubernetes cluster is built with Juju itself (via a bundle) and to Juju, making the usual combination of `add-cloud` and `add-credential` unnecessary. -User credentials can still be added by way of the `add-credential` -or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used -to add a new user to the k8s cluster. +User credentials can still be added by way of the `add-credential` or +`autoload-credentials` commands. Also, at any time, the k8s CLI can be used to +add a new user to the k8s cluster. The `add-k8s` command can be used repeatedly to set up different clusters as long as the contents of the configuration file has been changed accordingly. @@ -53,7 +49,7 @@ To summarise, the steps for using Kubernetes with Juju are: 1. Obtain a cluster 1. Add the cluster to Juju 1. Create a controller (and optionally a model) - 1. Deploy CAAS-specific charms + 1. Deploy k8s-specific charms ### Obtain a Kubernetes cluster @@ -63,7 +59,7 @@ by deploying a minimal two-machine Kubernetes cluster by making use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash -juju bootstrap localhost lxd-caas +juju bootstrap localhost lxd-k8s juju deploy kubernetes-core ``` @@ -135,7 +131,7 @@ juju add-k8s k8cloud ## Configuration -Juju CAAS applications support application specific configuration. This allows +Juju k8s applications support application specific configuration. This allows k8s configuration to be used to control how Juju deploys the application on Kubernetes. The following are supported (these names are the Juju configuration attribute names; the k8s meaning should be obvious): @@ -169,10 +165,6 @@ which allows for the addition or removal of units as normal. It remains possible to perform these same actions directly in the cluster by way of the Kubernetes `scale` command. -## Charms - - - @@ -180,4 +172,4 @@ Kubernetes `scale` command. [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [upstream-kubernetes-docs]: https://kubernetes.io/docs -[credentials]: ./credentials.html +[credentials]: ./credentials.md From dc622f5cc92a257d7c9d8aa3d0ba11519a3f6b41 Mon Sep 17 00:00:00 2001 From: Caleb Ellis Date: Mon, 9 Jul 2018 15:52:10 +0100 Subject: [PATCH 012/311] Update documentation homepage --- src/en/index.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ src/en/metadata.yaml | 8 +++- 2 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 src/en/index.md diff --git a/src/en/index.md b/src/en/index.md new file mode 100644 index 000000000..2ab7a2f8a --- /dev/null +++ b/src/en/index.md @@ -0,0 +1,90 @@ +--- +title: Home +homepage: true +--- + +
+
+

Juju Documentation

+

Juju is an open source application modeling tool. It allows you to deploy, configure, scale and operate your software on public and private clouds.

+
+
+
+
+
+
+

Getting started

+

Juju works with public cloud, private clouds, and locally with LXD.

+

Getting started with Juju ›

+
+
+ +
+
+
+
+
+

What's new

+ +
+
+

Explore Juju

+ +
+
+
+
+
+

Getting support

+ +
+
+

Contribute

+ +
+
+
+
diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 7e1a880bc..d4ed9521b 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -1,7 +1,11 @@ navigation: - - title: About Juju - location: about-juju.md + - title: Introduction + children: + - title: Home + location: index.md + - title: What is Juju? + location: about-juju.md - title: Quick Guides From 5810134d52fe947740503223f7568ab7928fe321 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 3 Aug 2018 16:08:48 -0400 Subject: [PATCH 013/311] pre-discourse WIP --- src/en/metadata.yaml | 350 +++++++++++-------------------------------- 1 file changed, 84 insertions(+), 266 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index f7450fd4f..7c880cbda 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -3,31 +3,24 @@ navigation: - title: About Juju location: about-juju.md - - title: Quick Guides + - title: Take a tour + location: getting-started.md - children: - - title: Get started - location: getting-started.md - - title: What's new in 2.4 - location: whats-new.md - - title: Local Juju with LXD cloud - location: tut-lxd.md - - title: Controllers and Models - location: tut-google.md - - title: Sharing and Users - location: tut-users.md + - title: Install Juju + location: reference-install.md + + - title: Release notes + location: reference-release-notes.md - title: User Guide children: - - title: Concepts and terms + - title: Concepts location: juju-concepts.md - title: Clouds location: clouds.md children: - - title: Cloud credentials - location: credentials.md - title: Amazon AWS location: help-aws.md - title: Microsoft Azure @@ -44,6 +37,8 @@ navigation: location: clouds-manual.md - title: OpenStack location: help-openstack.md + - title: Private cloud metadata + location: howto-privatecloud.md - title: Oracle Compute location: help-oracle.md - title: Rackspace @@ -51,28 +46,12 @@ navigation: - title: VMware vSphere location: help-vmware.md - - title: Juju client - location: client.md - - - title: Controllers - location: controllers.md - - children: - - title: Create/Bootstrap - location: controllers-creating.md - - title: Juju GUI - location: controllers-gui.md - - title: Controller high availability - location: controllers-ha.md - - title: Controller backups - location: controllers-backup.md - - - title: Models - location: models.md - - title: Charms & applications + - title: Using Juju location: charms.md children: + - title: Creating a controller + location: controllers-creating.md - title: Deploying applications location: charms-deploying.md - title: Using constraints @@ -81,244 +60,102 @@ navigation: location: charms-config.md - title: Managing relations location: charms-relations.md - - title: Exposing applications - location: charms-exposing.md - - title: Scaling applications + - title: Removing things + location: charms-destroy.md + + - title: Administering Juju + location: charms.md + + children: + - title: Juju users + location: users.md + - title: Scaling up and down location: charms-scaling.md - title: Upgrading applications location: charms-upgrading.md - - title: Removing applications & Units - location: charms-destroy.md - - title: Groups of applications - location: charms-service-groups.md - - title: Charm high availability + - title: Updating a machine series + location: howto-updateseries.md + - title: Controller backups + location: controllers-backup.md + - title: Controller high availability + location: controllers-ha.md + - title: Application high availability location: charms-ha.md - - title: Working with Units - location: charms-working-with-units.md - - title: Working with Actions - location: actions.md - - title: Working with Resources - location: charms-resources.md - - title: Using storage - location: charms-storage.md - - title: Viewing utilization with metrics - location: charms-metrics.md - - title: Fan container networking - location: charms-fan.md - - title: Working offline - location: charms-offline.md - - title: Charm bundles - location: charms-bundles.md - - title: Users - location: users.md + - title: Advanced topics children: - - title: Authentication - location: users-auth.md - - title: Creating users - location: users-creating.md - - title: Users and models - location: users-models.md - - title: User management - location: users-manage.md - - title: Sample commands - location: users-sample-commands.md - - title: Workflow scenarios - location: users-workflows.md + - title: Charm bundles + location: charms-bundles.md + - title: Using storage + location: charms-storage.md + - title: Working with actions + location: actions.md + - title: Working with resources + location: charms-resources.md + - title: Tools - - title: Managing Juju - location: juju-managing.md + - title: Networking children: - - title: Disable Juju commands - location: juju-block.md - - title: CentOS support - location: juju-centos.md + - title: Working offline + location: charms-offline.md + - title: Fan container networking + location: charms-fan.md - title: Network spaces location: network-spaces.md - - title: Juju plugins - location: juju-plugins.md - - - title: How to... - location: howto.md - - children: - - title: Configure metrics gathering with Prometheus - location: howto-prometheus.md - - title: Set up a Private Cloud - location: howto-privatecloud.md - - title: Update the series of a controller or machine - location: howto-updateseries.md - title: Troubleshooting location: troubleshooting.md - - title: Developer Guide + - title: Tutorials children: - - title: Getting Started - location: developer-getting-started.md - - children: - - title: Prerequisites and Tools - location: developer-getting-started#install-libraries-and-tools.md - - title: Designing your Charm - location: developer-getting-started#designing-your-charm.md - - title: Writing your Charm - location: developer-getting-started#writing-your-charm.md - - title: Testing your Charm - location: developer-getting-started#testing-your-charm.md - - title: Next steps - location: developer-getting-started#next-steps.md - - - title: Event Cycle - location: developer-event-cycle.md - - children: - - title: Handling Reactive States - location: developer-event-cycle#handling-reactive-states.md - - - title: Charm Layers - location: developer-layers.md - - children: - - title: What are Layers - location: developer-layers#what-are-layers?.md - - title: States - location: developer-layers#states.md - - title: How to Write a Layer - location: developer-layer-example.md - - - title: Interface Layers - location: developer-layers-interfaces.md - - children: - - title: Design Considerations - location: developer-layers-interfaces#design-considerations.md - - title: Communication Scopes - location: developer-layers-interfaces#communication-scopes.md - - title: Writing an Interface - location: developer-layers-interfaces#writing-an-interface-layer.md - - - title: Upgrading - location: developer-upgrade-charm.md - - title: Juju Terms - location: developer-terms.md - - title: Juju Metrics - location: developer-metrics.md - - title: Juju Resources - location: developer-resources.md - - title: Network Primitives - location: developer-network-primitives.md - - title: Implementing Leadership - location: developer-leadership.md - - children: - - title: Leadership Hooks - location: developer-leadership#leadership-hooks.md - - title: Leadership Tools - location: developer-leadership#leadership-tools.md - - title: Leadership Howtos - location: developer-leadership-howtos.md - - - title: Implementing Actions - location: developer-actions.md - - children: - - title: Defining Actions - location: developer-actions#implementing-actions.md - - title: Action Tools - location: developer-actions#action-tools.md - - - title: Implementing Storage - location: developer-storage.md - - children: - - title: Adding Storage - location: developer-storage#adding-storage.md - - title: Storage Hooks - location: developer-storage#storage-hooks.md - - - title: Writing Tests - location: developer-testing.md - - children: - - title: Charm Proof - location: developer-testing#charm-proof.md - - title: Amulet - location: developer-testing#amulet.md - - title: BundleTester - location: developer-testing#bundletester.md - - - title: Debugging - location: developer-debugging.md - - children: - - title: Debugging Layers - location: developer-debug-layers.md - - title: debug-hooks - location: developer-debugging#the-'debug-hooks'-command.md - - title: debug-log - location: developer-debugging#the-'debug-log'-command.md - - title: DHX - location: developer-debug-dhx.md - - - title: How to... - location: developer-howto.md - - children: - - title: Charm with Docker - location: howto-charm-with-docker.md - - - title: Charm Authors - location: authors-intro.md - - children: - - title: How hooks are run (Hook API) - location: authors-hook-environment.md - - title: Relations lifecycle - location: authors-relations-in-depth.md - - title: Implementing relations - location: authors-relations.md - - title: Charm leadership - location: authors-charm-leadership.md - - title: Hook Errors - location: authors-hook-errors.md - - title: Subordinate applications - location: authors-subordinate-applications.md - - - title: The Juju Charm Store - location: authors-charm-store.md - - children: - - title: Submit a charm - location: authors-charm-store#submitting-a-new-charm.md - - title: Charm store policy - location: authors-charm-policy.md - - title: Best practices - location: authors-charm-best-practice.md - - title: Charm Icons - location: authors-charm-icon.md + - title: Local Juju with LXD cloud + location: tut-lxd.md + - title: Controllers and Models + location: tut-google.md + - title: Sharing and Users + location: tut-users.md - - title: Tools + - title: Miscellaneous children: - - title: Charm Tools - location: tools-charm-tools.md - - title: Charm Helpers - location: tools-charm-helpers.md - - title: Amulet - location: tools-amulet.md - - title: Mojo - location: tools-mojo.md + - title: Juju GUI + location: controllers-gui.md + - title: Disable Juju commands + location: juju-block.md + - title: CentOS support + location: juju-centos.md + - title: Juju plugins + location: juju-plugins.md + - title: Configure metrics gathering with Prometheus + location: howto-prometheus.md + - title: Groups of applications + location: charms-service-groups.md + - title: Working with units + location: charms-working-with-units.md + - title: Viewing utilization with metrics + location: charms-metrics.md + - title: Exposing applications + location: charms-exposing.md + - title: Controllers + location: controllers.md + - title: Models + location: models.md + - title: Cloud credentials + location: credentials.md + - title: Juju client + location: client.md + - title: What's new in 2.4 + location: whats-new.md + + - title: Developer Guide - title: Reference children: - - title: Install Juju - location: reference-install.md - - title: Introducing Juju 2.0! + - title: Introducing Juju 2 location: introducing-2.md - title: Juju commands location: commands.md @@ -332,31 +169,12 @@ navigation: location: reference-hook-tools.md - title: metadata.yaml location: authors-charm-metadata.md - - title: Layers and charms.reactive - location: https://charmsreactive.readthedocs.io - - children: - - title: Decorators - location: https://charmsreactive.readthedocs.io/en/latest/charms.reactive.decorators.html - - title: Flags - location: https://charmsreactive.readthedocs.io/en/latest/charms.reactive.flags.html - - title: Triggers - location: https://charmsreactive.readthedocs.io/en/latest/triggers.html - - title: Relations - location: https://charmsreactive.readthedocs.io/en/latest/charms.reactive.relations.html - - title: Layer.yaml - location: reference-layer-yaml.md - - title: API docs location: http://godoc.org/github.com/juju/juju/api - - title: Release notes - location: reference-release-notes.md - title: Status values location: reference-status.md - title: Machine/unit numbering location: reference-numbering.md - - title: Charm Review Criteria - location: reference-reviewers.md - title: Contact us location: contact-us.md From 4ddd04dc34d84585c28f99c7f21fc226b4ae6dac Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 4 Sep 2018 17:08:01 -0400 Subject: [PATCH 014/311] begin with a new page --- src/en/clouds-gce.md | 296 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) create mode 100644 src/en/clouds-gce.md diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md new file mode 100644 index 000000000..87419d0fc --- /dev/null +++ b/src/en/clouds-gce.md @@ -0,0 +1,296 @@ +Title: Using Google GCE with Juju + +# Using Google GCE with Juju + +Juju already has knowledge of the GCE cloud, which means adding your GCE +account to Juju is quick and easy. + +You can see more specific information on Juju's GCE support (e.g. the +supported regions) by running: + +```bash +juju show-cloud google +``` + +If at any point you believe Juju's information is out of date (e.g. Google just +announced support for a new region), you can update Juju's public cloud data by +running: + +```bash +juju update-clouds +``` + +## Preparing your GCE account + +Although Juju knows how GCE works, there are a few tasks you must perform in +order to integrate your account with Juju. We give an overview of the steps +here: + + - Using the CLI tool + - Assigning permissions + - Gathering credential information + +!!! Note: + The Google Cloud Platform Console (web UI) can also be used to complete the + above steps. + +### Using the CLI tool + +We show how to use the [Cloud SDK tools][gcloud-docs] from Google to manage +your GCP (Google Cloud Platform) account. In particular, they will allow you to +collect your GCE credentials, which can then be added to Juju. + +Begin by installing the tool in this way: + +```bash +export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" +echo "deb http://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" \ + | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list +curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - +sudo apt update && sudo apt install google-cloud-sdk +``` + +Now initialise your GCE account: + +```bash +gcloud init +``` + +Among other things, you will be asked to enter a verification code in order to +log in to GCP. This code is gained by following a supplied hyperlink. + +You will also be given the choice of selecting an existing GCE project or of +creating a new one. + +At the completion of this command a default value for your user, project, +region, and zone will be set. The following command shows the result: + +```bash +gcloud config list +``` + +Sample output: + +```no-highlight +[compute] +region = us-east1 +zone = us-east1-d +[core] +account = javierlarin72@gmail.com +disable_usage_reporting = True +project = juju-gce-1225 +``` + +Projects can be listed like this: + +```bash +gcloud projects list +``` + +Output: + +```no-highlight +PROJECT_ID NAME PROJECT_NUMBER +juju-gce-1225 Juju-GCE 525743174537 +``` + +Information on a particular project can be shown in this way: + +```bash +gcloud projects describe juju-gce-1225 +``` + +Output: + +```no-highlight +createTime: '2016-02-18T01:00:10.043Z' +lifecycleState: ACTIVE +name: Juju-GCE +projectId: juju-gce-1225 +projectNumber: '525743174537' +``` + +The above outputs are what will be used in the remainder of this guide. + +See the [gcloud documentation][gcloud-docs] for in-depth coverage of Google's +Cloud SDK tools. + +### Assigning permissions + +The credentials you are looking for are not actually associated with your +user. They are instead linked to a *Compute Engine service account*. + +To download such credentials the user, as known to *gcloud*, must have the +authorisation to do so. This is done by assigning the *role* of 'Service +Account Key Admin'. + +To do this we need to include the project name and the user's email address: + +```bash +gcloud projects add-iam-policy-binding juju-gce-1225 \ + --member user:javierlarin72@gmail.com \ + --role roles/iam.serviceAccountKeyAdmin +``` + +On a per-project basis, you can list IAM members (user accounts and service +accounts) and their roles with: + +```bash +gcloud projects get-iam-policy juju-gce-1225 +``` + +### Managing service accounts + +Current service accounts are viewed in this way: + +```bash +gcloud iam service-accounts list +``` + +Sample output: + +```no-highlight +NAME EMAIL +App Engine default service account blah-gce-1225@appspot.gserviceaccount.com +Compute Engine default service account 525743174537-compute@developer.gserviceaccount.com +``` + +You can create a new service account if you are having trouble identifying an +existing one or if you want one dedicated to Juju. Here, we will create a new +one: + +```bash +gcloud iam service-accounts create juju-gce \ + --display-name "Compute Engine Juju service account" +``` + +The list of service accounts now becomes: + +```no-highlight +NAME EMAIL +App Engine default service account blah-gce-1225@appspot.gserviceaccount.com +Compute Engine default service account 525743174537-compute@developer.gserviceaccount.com +Compute Engine Juju service account juju-gce@juju-gce-1225.iam.gserviceaccount.com +``` + +### Gathering credential information + +You are now ready to download credentials for your chosen GCE service account. +Here we've called the download file `juju-gce.json`: + +```bash +gcloud iam service-accounts keys create juju-gce.json \ + --iam-account=juju-gce@juju-gce-1225.iam.gserviceaccount.com +``` + +Store this file in the Juju client directory (e.g. +`~/.local/share/juju/juju-gce.json`). + +The section [Using environment variables][#using-environment-variables] below +explains where this data can be stored if you wish to use the +`autoload-credentials` command to add credentials to Juju. + +## Adding credentials + +The [Cloud credentials][credentials] page offers a full treatment of credential +management. + +In order to access Google GCE, you will need to add credentials to Juju. This +can be done in one of three ways. + +### Using the interactive method + +Armed with the gathered information, you can add credentials with the command: + +```bash +juju add-credential google +``` + +The command will interactively prompt you for the information needed for the +chosen cloud. For the authentication type, choose 'json' and then give the full +path to the downloaded file. + +Alternately, you can use these credentials with [Juju as a Service][jaas] where +you can deploy charms using a web GUI. + +### Using a file + +A YAML-formatted file, say `mycreds.yaml`, can be used to store credential +information for any cloud. This information is then added to Juju by pointing +the `add-credential` command to the file: + +```bash +juju add-credential myopenstack -f mycreds.yaml +``` + +See section [Adding credentials from a file][credentials-adding-from-file] for +guidance on what such a file looks like. + +### Using environment variables + +With GCE you have the option of adding credentials using the following +environment variable that may already be present (and set) on your client +system: + +`CLOUDSDK_COMPUTE_REGION` + +In addition, a special variable may contain the path to a JSON-formatted file +which, in turn, contains credential information: + +`GOOGLE_APPLICATION_CREDENTIALS` + +Add this credential information to Juju in this way: + +```bash +juju autoload-credentials +``` + +For any found credentials you will be asked which ones to use and what name to +store them under. + +On Linux systems, the file +`$HOME/.config/gcloud/application_default_credentials.json` may be used to +contain credential data and is parsed by the above command as part of the +scanning process. On Windows systems, the file is +`%APPDATA%\gcloud\application_default_credentials.json`. + +For background information on this method read section +[Adding credentials from environment variables][credentials-adding-from-variables]. + +## Creating a controller + +You are now ready to create a Juju controller for cloud 'google': + +```bash +juju bootstrap google google-controller +``` + +Above, the name given to the new controller is 'google-controller'. GCE will +provision an instance to run the controller on. + +For a detailed explanation and examples of the `bootstrap` command see the +[Creating a controller][controllers-creating] page. + +## Next steps + +A controller is created with two models - the 'controller' model, which +should be reserved for Juju's internal operations, and a model named +'default', which can be used for deploying user workloads. + +See these pages for ideas on what to do next: + + - [Juju models][models] + - [Introduction to Juju Charms][charms] + + + + +[jaas]: ./getting-started.md +[controllers-creating]: ./controllers-creating.md +[models]: ./models.md +[charms]: ./charms.md +[credentials]: ./credentials.md +[credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file +[credentials-adding-from-variables]: ./credentials.md#adding-credentials-from-environment-variables +[#using-environment-variables]: #using-environment-variables +[gcloud-docs]: From 27b934c318a0fcd5ef19c02ef6df5918e0a13016 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 4 Sep 2018 19:39:24 -0400 Subject: [PATCH 015/311] more commands --- src/en/clouds-gce.md | 55 ++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index 87419d0fc..ea306846f 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -20,6 +20,10 @@ running: juju update-clouds ``` +The instructions on this page make use of the Identity and Access Management +(IAM) framework to control access to your GCP account. Read Google's +[Cloud IAM][gce-iam] page for an overview. + ## Preparing your GCE account Although Juju knows how GCE works, there are a few tasks you must perform in @@ -112,8 +116,10 @@ projectNumber: '525743174537' The above outputs are what will be used in the remainder of this guide. -See the [gcloud documentation][gcloud-docs] for in-depth coverage of Google's -Cloud SDK tools. +See these Google documents for further help: + + - [Google Cloud SDK Documentation][google-cloud-sdk-docs] + - [gcloud command reference][gcloud-commands] ### Assigning permissions @@ -141,20 +147,12 @@ gcloud projects get-iam-policy juju-gce-1225 ### Managing service accounts -Current service accounts are viewed in this way: +Current service accounts are listed in this way: ```bash gcloud iam service-accounts list ``` -Sample output: - -```no-highlight -NAME EMAIL -App Engine default service account blah-gce-1225@appspot.gserviceaccount.com -Compute Engine default service account 525743174537-compute@developer.gserviceaccount.com -``` - You can create a new service account if you are having trouble identifying an existing one or if you want one dedicated to Juju. Here, we will create a new one: @@ -164,7 +162,7 @@ gcloud iam service-accounts create juju-gce \ --display-name "Compute Engine Juju service account" ``` -The list of service accounts now becomes: +For our current example, the list of service accounts is now: ```no-highlight NAME EMAIL @@ -173,6 +171,20 @@ Compute Engine default service account 525743174537-compute@developer.gservicea Compute Engine Juju service account juju-gce@juju-gce-1225.iam.gserviceaccount.com ``` +We must now give our chosen GCE service account enough permissions to do what +Juju asks of it. The roles of 'Compute Instance Admin (v1)' and +'Compute Security Admin' are sufficient. Proceed in this way: + +```bash +gcloud projects add-iam-policy-binding juju-gce-1225 \ + --member serviceAccount:juju-gce@juju-gce-1225.iam.gserviceaccount.com \ + --role roles/compute.instanceAdmin.v1 \ + --role roles/compute.securityAdmin +``` + +IAM roles can be configured in multiple ways. See upstream document +[Compute Engine IAM Roles][gce-iam-roles] for full information. + ### Gathering credential information You are now ready to download credentials for your chosen GCE service account. @@ -220,7 +232,7 @@ information for any cloud. This information is then added to Juju by pointing the `add-credential` command to the file: ```bash -juju add-credential myopenstack -f mycreds.yaml +juju add-credential google -f mycreds.yaml ``` See section [Adding credentials from a file][credentials-adding-from-file] for @@ -239,6 +251,12 @@ which, in turn, contains credential information: `GOOGLE_APPLICATION_CREDENTIALS` +Finally, on Linux systems, the file +`$HOME/.config/gcloud/application_default_credentials.json` may be used to +contain credential data and is parsed by the above command as part of the +scanning process. On Windows systems, the file is +`%APPDATA%\gcloud\application_default_credentials.json`. + Add this credential information to Juju in this way: ```bash @@ -248,12 +266,6 @@ juju autoload-credentials For any found credentials you will be asked which ones to use and what name to store them under. -On Linux systems, the file -`$HOME/.config/gcloud/application_default_credentials.json` may be used to -contain credential data and is parsed by the above command as part of the -scanning process. On Windows systems, the file is -`%APPDATA%\gcloud\application_default_credentials.json`. - For background information on this method read section [Adding credentials from environment variables][credentials-adding-from-variables]. @@ -293,4 +305,7 @@ See these pages for ideas on what to do next: [credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file [credentials-adding-from-variables]: ./credentials.md#adding-credentials-from-environment-variables [#using-environment-variables]: #using-environment-variables -[gcloud-docs]: +[google-cloud-sdk-docs]: https://cloud.google.com/sdk/docs/ +[gcloud-commands]: https://cloud.google.com/sdk/gcloud/reference/ +[gce-iam]: https://cloud.google.com/iam/docs/overview +[gce-iam-roles]: https://cloud.google.com/compute/docs/access/iam From 6074c2aa0190ae205ec1e047cd948eec3eb9fd03 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 5 Sep 2018 21:53:56 -0400 Subject: [PATCH 016/311] more testing and writing --- src/en/clouds-gce.md | 195 ++++++++++++++++++++----------------------- 1 file changed, 89 insertions(+), 106 deletions(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index ea306846f..6c7ae6341 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -30,21 +30,25 @@ Although Juju knows how GCE works, there are a few tasks you must perform in order to integrate your account with Juju. We give an overview of the steps here: - - Using the CLI tool + - Using the CLI tools - Assigning permissions + - Managing service accounts - Gathering credential information !!! Note: - The Google Cloud Platform Console (web UI) can also be used to complete the - above steps. + The Google [Cloud Platform Console][google-cpc] (web UI) can also be used + to complete the above steps. -### Using the CLI tool +### Using the CLI tools -We show how to use the [Cloud SDK tools][gcloud-docs] from Google to manage -your GCP (Google Cloud Platform) account. In particular, they will allow you to -collect your GCE credentials, which can then be added to Juju. +We show how to use the [Cloud SDK tools][google-cloud-sdk-docs] from Google to +manage your GCP (Google Cloud Platform) account. In particular, they will allow +you to collect your GCE credentials, which can then be added to Juju. -Begin by installing the tool in this way: +The tools installation instructions presented here are for Ubuntu/Debian. See +the link above for how to install on other platforms. + +Install the tools in this way: ```bash export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" @@ -54,149 +58,114 @@ curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - sudo apt update && sudo apt install google-cloud-sdk ``` -Now initialise your GCE account: +Now initialise the tool: ```bash gcloud init ``` Among other things, you will be asked to enter a verification code in order to -log in to GCP. This code is gained by following a supplied hyperlink. +log in to GCP. This code is gained by following a supplied hyperlink, which, in +turn, will involve you pressing a button on the resulting page allowing Google +Cloud SDK to access your user's Google account. -You will also be given the choice of selecting an existing GCE project or of -creating a new one. +You will be given the choice of selecting an existing GCE project or of +creating a new one. If creating, pick a unique name to prevent the command from +exiting. If it does, re-invoke `gcloud init` and choose option [1] to +re-initialise. -At the completion of this command a default value for your user, project, -region, and zone will be set. The following command shows the result: +When you're done, try out the following commands (we created a project called +'juju-gce-123'): ```bash +gcloud components list gcloud config list -``` - -Sample output: - -```no-highlight -[compute] -region = us-east1 -zone = us-east1-d -[core] -account = javierlarin72@gmail.com -disable_usage_reporting = True -project = juju-gce-1225 -``` - -Projects can be listed like this: - -```bash gcloud projects list +gcloud projects describe juju-gce-123 ``` -Output: - -```no-highlight -PROJECT_ID NAME PROJECT_NUMBER -juju-gce-1225 Juju-GCE 525743174537 -``` - -Information on a particular project can be shown in this way: - -```bash -gcloud projects describe juju-gce-1225 -``` - -Output: - -```no-highlight -createTime: '2016-02-18T01:00:10.043Z' -lifecycleState: ACTIVE -name: Juju-GCE -projectId: juju-gce-1225 -projectNumber: '525743174537' -``` - -The above outputs are what will be used in the remainder of this guide. - -See these Google documents for further help: - - - [Google Cloud SDK Documentation][google-cloud-sdk-docs] - - [gcloud command reference][gcloud-commands] +See the [gcloud command reference][gcloud-commands] for more help with this +tool. ### Assigning permissions -The credentials you are looking for are not actually associated with your -user. They are instead linked to a *Compute Engine service account*. +Using the IAM framework, we'll be associating credentials with our project at +the *Compute Engine service account* level and not at the level of your +personal user. -To download such credentials the user, as known to *gcloud*, must have the -authorisation to do so. This is done by assigning the *role* of 'Service -Account Key Admin'. - -To do this we need to include the project name and the user's email address: +To download such credentials, however, your personal user (now known to the CLI +tool) must have the authorisation to do so. This is done by assigning the +*role* of 'Service Account Key Admin' to your user (insert your project ID and +user's email address): ```bash -gcloud projects add-iam-policy-binding juju-gce-1225 \ +gcloud projects add-iam-policy-binding juju-gce-123 \ --member user:javierlarin72@gmail.com \ --role roles/iam.serviceAccountKeyAdmin ``` -On a per-project basis, you can list IAM members (user accounts and service -accounts) and their roles with: - -```bash -gcloud projects get-iam-policy juju-gce-1225 -``` - ### Managing service accounts -Current service accounts are listed in this way: +A project's service accounts are listed in this way: ```bash -gcloud iam service-accounts list +gcloud iam service-accounts list --project juju-gce-123 ``` -You can create a new service account if you are having trouble identifying an -existing one or if you want one dedicated to Juju. Here, we will create a new -one: +You can create a new service account if: + + - you are having trouble identifying an existing one to use + - your project does not yet have any service accounts + - you want one dedicated to Juju + +Here, we will create a new one called 'juju-gce-sa': ```bash -gcloud iam service-accounts create juju-gce \ +gcloud iam service-accounts create juju-gce-sa \ --display-name "Compute Engine Juju service account" ``` -For our current example, the list of service accounts is now: +For our example project, the list of service accounts is now: ```no-highlight NAME EMAIL -App Engine default service account blah-gce-1225@appspot.gserviceaccount.com -Compute Engine default service account 525743174537-compute@developer.gserviceaccount.com -Compute Engine Juju service account juju-gce@juju-gce-1225.iam.gserviceaccount.com +Compute Engine Juju service account juju-gce-sa@juju-gce-123.iam.gserviceaccount.com ``` -We must now give our chosen GCE service account enough permissions to do what -Juju asks of it. The roles of 'Compute Instance Admin (v1)' and -'Compute Security Admin' are sufficient. Proceed in this way: +We must now give our chosen service account enough permissions so it can do +what Juju asks of it. The roles of 'Compute Instance Admin (v1)' and 'Compute +Security Admin' are sufficient: ```bash -gcloud projects add-iam-policy-binding juju-gce-1225 \ - --member serviceAccount:juju-gce@juju-gce-1225.iam.gserviceaccount.com \ - --role roles/compute.instanceAdmin.v1 \ +gcloud projects add-iam-policy-binding juju-gce-123 \ + --member serviceAccount:juju-gce-sa@juju-gce-123.iam.gserviceaccount.com \ + --role roles/compute.instanceAdmin.v1 +gcloud projects add-iam-policy-binding juju-gce-123 \ + --member serviceAccount:juju-gce-sa@juju-gce-123.iam.gserviceaccount.com \ --role roles/compute.securityAdmin ``` -IAM roles can be configured in multiple ways. See upstream document -[Compute Engine IAM Roles][gce-iam-roles] for full information. +Permissions can be configured in multiple ways due to the many IAM roles +available. See upstream document [Compute Engine IAM Roles][gce-iam-roles] for +details. + +Verify the roles now assigned to both your user and your service account: + +```bash +gcloud projects get-iam-policy juju-gce-123 +``` ### Gathering credential information -You are now ready to download credentials for your chosen GCE service account. -Here we've called the download file `juju-gce.json`: +You are now ready to download credentials for your chosen service account. +Here we've called the download file `juju-gce-sa.json`: ```bash -gcloud iam service-accounts keys create juju-gce.json \ - --iam-account=juju-gce@juju-gce-1225.iam.gserviceaccount.com +gcloud iam service-accounts keys create juju-gce-sa.json \ + --iam-account=juju-gce-sa@juju-gce-123.iam.gserviceaccount.com ``` -Store this file in the Juju client directory (e.g. -`~/.local/share/juju/juju-gce.json`). +Store this file on the Juju client (e.g. `~/.local/share/juju/juju-gce-sa.json`). The section [Using environment variables][#using-environment-variables] below explains where this data can be stored if you wish to use the @@ -208,22 +177,35 @@ The [Cloud credentials][credentials] page offers a full treatment of credential management. In order to access Google GCE, you will need to add credentials to Juju. This -can be done in one of three ways. +can be done in one of three ways (as shown below). + +Alternately, you can use your credentials with [Juju as a Service][jaas], where +charms can be deployed using a web GUI. ### Using the interactive method -Armed with the gathered information, you can add credentials with the command: +Armed with the gathered information, credentials can be added interactively: ```bash juju add-credential google ``` -The command will interactively prompt you for the information needed for the -chosen cloud. For the authentication type, choose 'json' and then give the full -path to the downloaded file. +The command will prompt you for information that the chosen cloud needs. An +example session follows: + +```no-highlight +Enter credential name: juju-gce-sa + +Auth Types + jsonfile + oauth2 + +Select auth type [jsonfile]: -Alternately, you can use these credentials with [Juju as a Service][jaas] where -you can deploy charms using a web GUI. +Enter file: ~/.local/share/juju/juju-gce-sa.json + +Credential "juju-gce-sa" added locally for cloud "google".` +``` ### Using a file @@ -309,3 +291,4 @@ See these pages for ideas on what to do next: [gcloud-commands]: https://cloud.google.com/sdk/gcloud/reference/ [gce-iam]: https://cloud.google.com/iam/docs/overview [gce-iam-roles]: https://cloud.google.com/compute/docs/access/iam +[google-cpc]: https://console.cloud.google.com/ From f14878651125a145e80fdbb28d7ee0816ff6927c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 6 Sep 2018 11:58:46 -0400 Subject: [PATCH 017/311] add example entry to credentials page; add API enabling --- src/en/clouds-gce.md | 55 ++++++++++++++++++++++++++++++++++++------- src/en/credentials.md | 34 ++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 8 deletions(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index 6c7ae6341..b37828a93 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -20,10 +20,6 @@ running: juju update-clouds ``` -The instructions on this page make use of the Identity and Access Management -(IAM) framework to control access to your GCP account. Read Google's -[Cloud IAM][gce-iam] page for an overview. - ## Preparing your GCE account Although Juju knows how GCE works, there are a few tasks you must perform in @@ -31,14 +27,19 @@ order to integrate your account with Juju. We give an overview of the steps here: - Using the CLI tools - - Assigning permissions + - Assigning user permissions - Managing service accounts - Gathering credential information + - Enabling the Compute Engine API !!! Note: The Google [Cloud Platform Console][google-cpc] (web UI) can also be used to complete the above steps. +The instructions on this page make use of the Identity and Access Management +(IAM) framework to control access to your GCP account. Read Google's +[Cloud IAM][gce-iam] page for an overview. + ### Using the CLI tools We show how to use the [Cloud SDK tools][google-cloud-sdk-docs] from Google to @@ -75,7 +76,7 @@ exiting. If it does, re-invoke `gcloud init` and choose option [1] to re-initialise. When you're done, try out the following commands (we created a project called -'juju-gce-123'): +'juju-gce-123' during the init phase): ```bash gcloud components list @@ -87,7 +88,7 @@ gcloud projects describe juju-gce-123 See the [gcloud command reference][gcloud-commands] for more help with this tool. -### Assigning permissions +### Assigning user permissions Using the IAM framework, we'll be associating credentials with our project at the *Compute Engine service account* level and not at the level of your @@ -95,7 +96,7 @@ personal user. To download such credentials, however, your personal user (now known to the CLI tool) must have the authorisation to do so. This is done by assigning the -*role* of 'Service Account Key Admin' to your user (insert your project ID and +role of 'Service Account Key Admin' to your user (insert your project ID and user's email address): ```bash @@ -171,6 +172,44 @@ The section [Using environment variables][#using-environment-variables] below explains where this data can be stored if you wish to use the `autoload-credentials` command to add credentials to Juju. +### Enabling the Compute Engine API + +The Compute Engine API needs to be enabled for your project but this requires +your billing account to be first linked to your project. + +Your billing (credit card) should have been set up when you registered with +GCE. To see your billing account number: + +```bash +gcloud alpha billing accounts list +``` + +Sample output: + +```no-highlight +ACCOUNT_ID NAME OPEN MASTER_ACCOUNT_ID +01ACD0-B3D759-187641 My Billing Account True +``` + +Use the account number/ID to link your project: + +```bash +gcloud alpha billing projects link juju-gce-123 --billing-account 01ACD0-B3D759-187641 +``` + +You can now enable the Compute Engine API for your project (this can take a few +minutes to complete): + +```bash +gcloud services enable compute.googleapis.com --project juju-gce-123 +``` + +Verify by listing all currently enabled services/APIs: + +```bash +gcloud services list --project juju-gce-123 +``` + ## Adding credentials The [Cloud credentials][credentials] page offers a full treatment of credential diff --git a/src/en/credentials.md b/src/en/credentials.md index 9d5fb9602..b3b28e616 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -141,6 +141,40 @@ credentials: peter: auth-type: jsonfile file: ~/.config/gcloud/application_default_credentials.json + juju-gce-sa: + auth-type: oauth2 + project-id: juju-gce-123 + private-key: | + -----BEGIN PRIVATE KEY----- + MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCzTFMj0/GvhrcZ + 3B2584ZdDdsnVuHb7OYo8eqXVLYzXEkby0TMu2gM81LdGp6AeeB3nu5zwAf71YyP + erF4s0falNPIyRjDGYV1wWR+mRTbVjYUd/Vuy+KyP0u8UwkktwkP4OFR270/HFOl + Kc0rzflag8zdKzRhi7U1dlgkchbkrio148vdaoZZo67nxFVF2IY52I2qGW8VFdid + z+B9pTu2ZQKVeEpTVe5XEs3y2Y4zt2DCNu3rJi95AY4VDgVJ5f1rnWf7BwZPeuvp + 0mXLKzcvD31wEcdE6oAaGu0x0UzKvEB1mR1pPwP6qMHdiJXzkiM9DYylrMzuGL/h + VAYjhFQnAgMBAAECggEADTkKkJ10bEt1FjuJ5BYCyYelRLUMALO4RzpZrXUArHz/ + CN7oYTWykL68VIE+dNJU+Yo6ot99anC8GWclAdyTs5nYnJNbRItafYd+3JwRhU0W + vYYZqMtXs2mNMYOC+YNkibIKxYZJ4joGksTboRvJne4TN7Et/1uirr+GtLPn+W/e + umXfkpbOTDDAED8ceKKApAn6kLIW98DwHyK0rUzorOgp4DFDX9CjuWC+RG3CFGsk + oVOcDuTevJlb9Rowj1S2qYhGjuQVpVD7bcRg5zaSJKS88YbK63DCHZFpXn9JR0Fg + Vou9dnc99FdMo5vtHg7Adxh91gdqEvoaF1lHx8Var0q32QDse+spvv7K6/+7G35k + 3+1gDgF74/uMr/AVrjpoUjmGAuWweXY/vn1MVN2Uld4KPYafkOF8oTuDK5f1fu0d + cMEoKRSXQh1NCD3PZWfQt4ypYPzn9R+VBGwnBcPorytlhM9qdLxKKlaHjBlprS6Y + Be1z6FO+MqWhFlwPrKH/2uwd4QKBgQDCGESJur9OdEeroBQyYyJF7DnJ/+wHSiOr + qzvb9YW1Ddtg1iiKHHZO5FS59/D62kPaGsysCMKxI9FW53TzSxUiTaEG636C5v8J + eRdzxX04BNYNzqXbm1agBEjAa7tK8xJAjk0to4zqadUaYZog0uQs2X7Aexj2c9T/ + HQVLILHjBwKBgD/yuoLNbST+cGbuZl1s2EnTP796xPkkUm3qcUzofzmn6uivz7Qp + FMThZhHZ/Der98tra91a4e8fHaUTL5d4eCMeCL1mWXoNMnm02D/ugpEC8yDefi3T + xlM/Ed0IEVogcd49tvTvQfrhfbW/6Que/rkLKCoUlAldfIOYkS4YyyTBAoGACCpH + L9gYVi+UGEc6skfzWCew4quOfVwEFiO09/LjNhOoJ/G6cNzzqSv32H7yt0rZUeKQ + u6f+sL8F/nbsN5PwBqpnXMgpYU5gakCa2Pb05pdlfd00owFs6nxjpxyhG20QVoDm + BEZ+FhpvqZVzi2/zw2M+7s/+49dJnZXV9Cwi758CgYAquNdD4RXU96Y2OjTlOSvM + THR/zY6IPeO+kCwmBLiQC3cv59gaeOp1a93Mnapet7a2/WZPL2Al7zwnvZYsHc4z + nu1acd6D7H/9bb1YPHMNWITfCSNXerJ2idI689ShYjR2sTcDgiOQCzx+dwL9agaC + WKjypRHpiAMFbFqPT6W2uA== + -----END PRIVATE KEY----- + client-id: "206517233375074786882" + client-email: juju-gce-sa@juju-gce-123.iam.gserviceaccount.com azure: peter: auth-type: service-principal-secret From a4a13dca243cb40630b211c941cb8b0f18c0eae9 Mon Sep 17 00:00:00 2001 From: Anthony Dillon Date: Thu, 6 Sep 2018 17:33:00 +0100 Subject: [PATCH 018/311] Point search at www.ubunut.com until we have custom search working on this project --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 10fd30b79..b852741e3 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "scripts": { "clean": "rm -rf node_modules build yarn-error.log css static/css *.log *.sqlite .extra templates", "watch": "watch -p './**/*.md' -c 'yarn run build'", - "build": "documentation-builder --template-path src/base.tpl --source-folder src --media-path src/en/media --output-media-path build/en/media --tag-manager-code 'GTM-K92JCQ' --search-domain 'docs.jujucharms.com' --search-url 'https://docs.ubuntu.com/search' --search-placeholder 'Search Juju docs' --no-link-extensions --build-version-branches --site-root https://jujucharms.com/" + "build": "documentation-builder --template-path src/base.tpl --source-folder src --media-path src/en/media --output-media-path build/en/media --tag-manager-code 'GTM-K92JCQ' --search-domain 'docs.jujucharms.com' --search-url 'https://www.ubuntu.com/search' --search-placeholder 'Search Juju docs' --no-link-extensions --build-version-branches --site-root https://jujucharms.com/" }, "dependencies": { "watch-cli": "^0.2.2", From d64e5bf4831327fc482197de6770bff6fe7e7f0a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 7 Sep 2018 17:45:06 -0400 Subject: [PATCH 019/311] finalise the 'to' option and fixup controller creation examples --- src/en/charms-deploying-advanced.md | 79 ++++++++++-------- src/en/controllers-creating.md | 121 ++++++++++++++++++---------- 2 files changed, 122 insertions(+), 78 deletions(-) diff --git a/src/en/charms-deploying-advanced.md b/src/en/charms-deploying-advanced.md index 4dbcc17e6..2fb0b4adc 100644 --- a/src/en/charms-deploying-advanced.md +++ b/src/en/charms-deploying-advanced.md @@ -75,24 +75,37 @@ details. ## Deploying to specific machines -To deploy to specific, pre-existing machines the `--to` option is used. When -this is done, unless the machine was created via `add-machine`, a charm has -already been deployed to the machine. +To deploy to specific machines the `--to` option is used. When this is done, +unless the machine was created via `add-machine`, a charm has already been +deployed to the machine. -!!! Note: +!!! Warning: When multiple charms are deployed to the same machine there exists the possibility of conflicting configuration files (on the machine's - filesystem). Work is being done to rectify this. + filesystem). -Machines are often referred to by their ID number. This is a simple integer -that is shown in the output to `juju status` (or `juju machines`). For example, -this partial output shows a machine with an ID of '2': +The `--to` option can be used with commands `bootstrap`, `deploy`, and +`add-unit`. + +To apply this option towards an existing Juju machine, the machine ID is used. +This is an integer that is shown in the output to `juju status` (or +`juju machines`). For example, this partial output shows a machine with an ID +of '2': ```no-highlight Machine State DNS Inst id Series AZ Message 2 started 10.132.70.65 juju-79b3aa-0 xenial Running ``` +The above works well with `deploy` and `add-unit` as will be shown below. As +for `bootstrap` the `--to` option is limited to pointing to a MAAS node. +Assuming a MAAS cloud has been added and is called 'maas-prod' you can +therefore do this: + +```bash +juju bootstrap maas-prod --to .maas +``` + ### deploy --to To deploy the 'haproxy' application to machine '2' we would do this: @@ -113,34 +126,32 @@ juju deploy --to 0 rabbitmq-server ``` Juju treats a container like any other machine so it is possible to target -specific containers as well. Here we deploy to containers in two different +specific containers as well. Here we deploy to containers in three different ways: ```bash -juju deploy nginx --to 24/lxd/3 +juju deploy mariadb --to lxd juju deploy mongodb --to lxd:25 +juju deploy nginx --to 24/lxd/3 ``` -In the first case above, nginx is deployed to existing container '3' on machine -'24'. In the second case, MongoDB is deployed to a **new** container on machine -'25'. The latter is an exception to the rule that the `--to` option is always -used in conjunction with a pre-existing machine. +In the first case, mariadb is deployed to a container on a new machine. In the +second case, MongoDB is deployed to a new container on existing machine '25'. +In the third case, nginx is deployed to existing container '3' on existing +machine '24'. -It is also possible to deploy units using *placement directives* as arguments -to the `--to` option. Placement directives are cloud-specific: +Some clouds support special arguments to the `--to` option, where instead of +a machine you can specify a zone or, in the case of MAAS, an underlying +physical (or virtual) machine: ```bash juju deploy mysql --to zone=us-east-1a juju deploy mediawiki --to host.mass ``` -The first example deploys to a specific AWS zone while the second example -deploys to a named machine in MAAS. - ### add-unit --to -The `add-unit` command also supports the `--to` option, including placement -directives. For example, to add a unit of 'rabbitmq-server' to machine '1': +To add a unit of 'rabbitmq-server' to machine '1': ```bash juju add-unit --to 1 rabbitmq-server @@ -151,12 +162,12 @@ where more than one unit is being added: ```bash juju add-unit rabbitmq-server -n 4 --to zone=us-west-1a,zone=us-east-1b -juju add-unit rabbitmq-server -n 4 --to host1,host2,host3,host4 +juju add-unit rabbitmq-server -n 3 --to host1.maas,host2.maas,host3.maas ``` -Any extra placement directives are ignored. If not enough placement directives -are supplied, then the remaining units will be assigned as normal to a new, -clean machine. +If the number of values is less than the number of requested units the +remaining units, as per normal behaviour, will be deployed to new machines. Any +surplus values are ignored. The `add-unit` command is often associated with scaling out. See the [Scaling applications][charms-scaling] page for information on that topic. @@ -260,12 +271,12 @@ mediawiki page. -[charms-deploying]: ./charms-deploying.html -[network-spaces]: ./network-spaces.html -[charms-bundles-endpoints]: ./charms-bundles.html#binding-endpoints-of-applications-within-a-bundle -[extra-bindings]: ./authors-charm-metadata.html#extra-bindings-field -[clouds-maas]: ./clouds-maas.html -[charms-contraints-spaces]: ./charms-constraints.html#adding-a-machine-with-constraints -[concepts-endpoint]: ./juju-concepts.html#endpoint -[charms-upgrading-forced]: ./charms-upgrading.html#forced-upgrades -[charms-scaling]: ./charms-scaling.html +[charms-deploying]: ./charms-deploying.md +[network-spaces]: ./network-spaces.md +[charms-bundles-endpoints]: ./charms-bundles.md#binding-endpoints-of-applications-within-a-bundle +[extra-bindings]: ./authors-charm-metadata.md#extra-bindings-field +[clouds-maas]: ./clouds-maas.md +[charms-contraints-spaces]: ./charms-constraints.md#adding-a-machine-with-constraints +[concepts-endpoint]: ./juju-concepts.md#endpoint +[charms-upgrading-forced]: ./charms-upgrading.md#forced-upgrades +[charms-scaling]: ./charms-scaling.md diff --git a/src/en/controllers-creating.md b/src/en/controllers-creating.md index d51a6ebd9..decd9fae7 100644 --- a/src/en/controllers-creating.md +++ b/src/en/controllers-creating.md @@ -1,31 +1,53 @@ -Title: Creating a Juju Controller -TODO: Improve examples - Hardcoded: Ubuntu code names - Update default controller release (to "latest LTS") and remove Note once 18.04.1 released - +Title: Creating a controller +TODO: Hardcoded: Ubuntu code names + Update default controller release (to Bionic) and remove Note once 18.04.1 released (juju v2.4 only) # Creating a controller -Use the `juju bootstrap` command to create a controller (and 'default' model) -for a given cloud: - -`juju bootstrap [options] []` +The `bootstrap` command is used to create a controller for a given cloud: -See `juju help bootstrap` for details on this command or see the -[Juju command reference][commands] page. +`juju bootstrap []` -The `` is optional. If one is not supplied, then a name is +The controller name is optional. If one is not supplied, then a name is assigned based on the cloud and region. To learn about configuration options available at bootstrap time, see: - - [Configuring controllers][controlconfig] - - [Configuring models][modelconfig] + - [Configuring controllers][controllers-config] + - [Configuring models][models-config] - [Using constraints][charms-constraints] ## Examples -### Set default model constraints for a given controller +This list of examples provides a good overview of the different things that can +be done at controller-creation time: + + - [Create a controller interactively][#create-a-controller-interactively] + - [Set default model constraints for a controller][#set-default-model-constraints-for-a-controller] + - [Set controller constraints for a new controller][#set-controller-constraints-for-a-new-controller] + - [Create a controller of a specific series][#create-a-controller-of-a-specific-series] + - [Create a controller using configuration values][#create-a-controller-using-configuration-values] + - [Create a controller using a non-default region][#create-a-controller-using-a-non-default-region] + - [Create a controller using a different MongoDB profile][#create-a-controller-using-a-different-mongodb-profile] + - [Change timeout and retry delays][#change-timeout-and-retry-delays] + - [Create a new controller without changing contexts][#create-a-new-controller-without-changing-contexts] + - [Configuring/enabling a remote syslog server][#configuring/enabling-a-remote-syslog-server] + - [Placing a controller on a specific MAAS node][#placing-a-controller-on-a-specific-maas-node] + - [Specifying an agent version][#specifying-an-agent-version] + - [Passing a cloud-specific setting][#passing-a-cloud-specific-setting] + +### Create a controller interactively + +You can create a controller interactively like this: + +```bash +juju bootstrap +``` + +You will be prompted for what cloud and region to use as well as the controller +name. Do not use this method if you want to specify anything else. + +### Set default model constraints for a controller Below, all machines (including the controller) in the LXD controller's models will have at least 4GiB of memory: @@ -70,14 +92,11 @@ requested explicitly (and is given the name 'gce-bionic'): juju bootstrap --bootstrap-series=bionic google gce-bionic ``` -### Create a Rackspace controller using a daily image - -The example uses a previously defined configuration file called -config-rackspace.yaml. +### Create a controller using configuration values -Note that values passed using '--config' will take precedence -over values included in a file. This is important if you use both a config -file and state one or more config values while bootstrapping. +This example uses a previously defined configuration file called +config-rackspace.yaml as well as individual configuration values. The latter +values take precedence over those included in the file: ```bash juju bootstrap \ @@ -88,17 +107,16 @@ juju bootstrap \ ### Create a controller using a non-default region -The [Clouds][clouds] page details listing available clouds and how the list -denotes default regions for each. To specify a different region during -controller creation, use: +The `clouds` command lists available clouds and denotes a default region for +each. To specify a different region during controller creation: ```bash juju bootstrap aws/us-west-2 mycontroller ``` -This is an instance where using the default controller name could be especially -handy, as omitting the `mycontroller` name will cause your new controller to be -named using the non-default region, specifically naming it `aws-us-west-2`: +This is where omitting a custom controller name could be appropriate, as doing +so will result in a name based on the non-default region. Here the controller +would be named 'aws-us-west-2': ```bash juju bootstrap aws/us-west-2 @@ -133,16 +151,11 @@ from 10 minutes to 15, enter the value in seconds: juju bootstrap --config bootstrap-timeout=900 localhost lxd-faraway ``` -### Changing the current model/controller +### Create a new controller without changing contexts -By default, when Juju bootstraps a new controller, it will also 'switch' to -that controller and the default model created with it. Any subsequent Juju -commands which do not specify a controller/model will be assumed to apply to -this model. - -In some cases (e.g. when scripting Juju) this may not be desirable. It is -possible to add a `--no-switch` option to the bootstrap command to prevent the -new controller from being automatically selected. For example: +When a new controller is created, by default, the context will change to the +'default' model of that controller. In some cases (e.g. when scripting) this +may not be desirable. The `--no-switch` option disables this behaviour: ```bash juju bootstrap --no-switch localhost lxd-new @@ -165,6 +178,14 @@ juju bootstrap azure --config logforward-enabled=true --config logconfig.yaml See [Remote logging][troubleshooting-logs-remote] for a more thorough treatment of log forwarding. +### Placing a controller on a specific MAAS node + +To create a controller and have it run on a specific MAAS node: + +```bash +juju bootstrap maas-prod --to .maas +``` + ### Specifying an agent version When a controller is created, it is possible to influence what agent version @@ -212,10 +233,22 @@ juju boootstrap --config vpc-id=vpc-86f7bbe1 aws -[clouds]: ./clouds.html -[charms-constraints]: ./charms-constraints.html -[commands]: ./commands.html#juju-bootstrap -[controlconfig]: ./controllers-config.html "Configuring Juju controllers" -[modelconfig]: ./models-config.html "Configuring Juju models" -[troubleshooting-logs-remote]: ./troubleshooting-logs-remote.html -[agent-versions-and-streams]: ./models-config.html#agent-versions-and-streams +[charms-constraints]: ./charms-constraints.md +[controllers-config]: ./controllers-config.md +[models-config]: ./models-config.md +[troubleshooting-logs-remote]: ./troubleshooting-logs-remote.md +[agent-versions-and-streams]: ./models-config.md#agent-versions-and-streams + +[#create-a-controller-interactively]: #create-a-controller-interactively +[#set-default-model-constraints-for-a-controller]: #set-default-model-constraints-for-a-controller +[#set-controller-constraints-for-a-new-controller]: #set-controller-constraints-for-a-new-controller +[#create-a-controller-of-a-specific-series]: #create-a-controller-of-a-specific-series +[#create-a-controller-using-configuration-values]: #create-a-controller-using-configuration-values +[#create-a-controller-using-a-non-default-region]: #create-a-controller-using-a-non-default-region +[#create-a-controller-using-a-different-mongodb-profile]: #create-a-controller-using-a-different-mongodb-profile +[#change-timeout-and-retry-delays]: #change-timeout-and-retry-delays +[#create-a-new-controller-without-changing-contexts]: #create-a-new-controller-without-changing-contexts +[#configuring/enabling-a-remote-syslog-server]: #configuring/enabling-a-remote-syslog-server +[#placing-a-controller-on-a-specific-maas-node]: #placing-a-controller-on-a-specific-maas-node +[#specifying-an-agent-version]: #specifying-an-agent-version +[#passing-a-cloud-specific-setting]: #passing-a-cloud-specific-setting From cbf4b938eb48ff9d9bfd23661d0bed979f7574c1 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 7 Sep 2018 18:26:17 -0400 Subject: [PATCH 020/311] bionic is the default for 2.4 --- src/en/controllers-creating.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/src/en/controllers-creating.md b/src/en/controllers-creating.md index decd9fae7..e218ef91e 100644 --- a/src/en/controllers-creating.md +++ b/src/en/controllers-creating.md @@ -1,6 +1,5 @@ Title: Creating a controller TODO: Hardcoded: Ubuntu code names - Update default controller release (to Bionic) and remove Note once 18.04.1 released (juju v2.4 only) # Creating a controller @@ -70,26 +69,22 @@ given via `--bootstrap-constraints` will be used. ### Create a controller of a specific series -The controller will be deployed upon Ubuntu 16.04 LTS (Xenial) by default. +The controller will be deployed upon Ubuntu 18.04 LTS (Bionic) by default. -For our example, we name the resulting LXD controller 'lxd-xenial' to reflect +For our example, we name the resulting LXD controller 'lxd-bionic' to reflect that: ```bash -juju bootstrap localhost lxd-xenial +juju bootstrap localhost lxd-bionic ``` -!!! Note: - The default release will change from Xenial to Ubuntu 18.04 LTS (Bionic) - once 18.04.1 is released (July 2018). - To select a different series the `--bootstrap-series` option is used. -Below, a google (GCE) controller based on Ubuntu 18.04 LTS (Bionic) is -requested explicitly (and is given the name 'gce-bionic'): +Below, a google (GCE) controller based on Ubuntu 16.04 LTS (Xenial) is +requested explicitly (and is given the name 'gce-xenial'): ```bash -juju bootstrap --bootstrap-series=bionic google gce-bionic +juju bootstrap --bootstrap-series=xenial google gce-xenial ``` ### Create a controller using configuration values From d4d9e77389c35e757e0cfc973bbae6cfdd896d70 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 8 Sep 2018 20:49:51 -0400 Subject: [PATCH 021/311] explain relation between project and credentials; rename project, sa, and credential name --- src/en/clouds-gce.md | 72 +++++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index b37828a93..592f39f40 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -43,11 +43,9 @@ The instructions on this page make use of the Identity and Access Management ### Using the CLI tools We show how to use the [Cloud SDK tools][google-cloud-sdk-docs] from Google to -manage your GCP (Google Cloud Platform) account. In particular, they will allow -you to collect your GCE credentials, which can then be added to Juju. - -The tools installation instructions presented here are for Ubuntu/Debian. See -the link above for how to install on other platforms. +manage your GCP (Google Cloud Platform) account. The tools installation +instructions presented here are for Ubuntu/Debian. See the link above for how +to install on other platforms. Install the tools in this way: @@ -66,9 +64,9 @@ gcloud init ``` Among other things, you will be asked to enter a verification code in order to -log in to GCP. This code is gained by following a supplied hyperlink, which, in -turn, will involve you pressing a button on the resulting page allowing Google -Cloud SDK to access your user's Google account. +log in to GCP. This code is acquired by following a supplied hyperlink, which, +in turn, will have you agree on the resulting page to allow Google Cloud SDK to +access your Google account. You will be given the choice of selecting an existing GCE project or of creating a new one. If creating, pick a unique name to prevent the command from @@ -76,13 +74,13 @@ exiting. If it does, re-invoke `gcloud init` and choose option [1] to re-initialise. When you're done, try out the following commands (we created a project called -'juju-gce-123' during the init phase): +'juju-gce-1' during the init phase): ```bash gcloud components list gcloud config list gcloud projects list -gcloud projects describe juju-gce-123 +gcloud projects describe juju-gce-1 ``` See the [gcloud command reference][gcloud-commands] for more help with this @@ -92,15 +90,15 @@ tool. Using the IAM framework, we'll be associating credentials with our project at the *Compute Engine service account* level and not at the level of your -personal user. +Google user. -To download such credentials, however, your personal user (now known to the CLI -tool) must have the authorisation to do so. This is done by assigning the -role of 'Service Account Key Admin' to your user (insert your project ID and +To download such credentials, however, your user (now known to the CLI tool) +must have the authorisation to do so. This is done by assigning the role of +'Service Account Key Admin' to your user (insert your project ID and your user's email address): ```bash -gcloud projects add-iam-policy-binding juju-gce-123 \ +gcloud projects add-iam-policy-binding juju-gce-1 \ --member user:javierlarin72@gmail.com \ --role roles/iam.serviceAccountKeyAdmin ``` @@ -110,7 +108,7 @@ gcloud projects add-iam-policy-binding juju-gce-123 \ A project's service accounts are listed in this way: ```bash -gcloud iam service-accounts list --project juju-gce-123 +gcloud iam service-accounts list --project juju-gce-1 ``` You can create a new service account if: @@ -119,10 +117,10 @@ You can create a new service account if: - your project does not yet have any service accounts - you want one dedicated to Juju -Here, we will create a new one called 'juju-gce-sa': +Here, we will create a new one called 'juju-gce-1-sa': ```bash -gcloud iam service-accounts create juju-gce-sa \ +gcloud iam service-accounts create juju-gce-1-sa \ --display-name "Compute Engine Juju service account" ``` @@ -130,7 +128,7 @@ For our example project, the list of service accounts is now: ```no-highlight NAME EMAIL -Compute Engine Juju service account juju-gce-sa@juju-gce-123.iam.gserviceaccount.com +Compute Engine Juju service account juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com ``` We must now give our chosen service account enough permissions so it can do @@ -138,11 +136,11 @@ what Juju asks of it. The roles of 'Compute Instance Admin (v1)' and 'Compute Security Admin' are sufficient: ```bash -gcloud projects add-iam-policy-binding juju-gce-123 \ - --member serviceAccount:juju-gce-sa@juju-gce-123.iam.gserviceaccount.com \ +gcloud projects add-iam-policy-binding juju-gce-1 \ + --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ --role roles/compute.instanceAdmin.v1 -gcloud projects add-iam-policy-binding juju-gce-123 \ - --member serviceAccount:juju-gce-sa@juju-gce-123.iam.gserviceaccount.com \ +gcloud projects add-iam-policy-binding juju-gce-1 \ + --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ --role roles/compute.securityAdmin ``` @@ -153,20 +151,20 @@ details. Verify the roles now assigned to both your user and your service account: ```bash -gcloud projects get-iam-policy juju-gce-123 +gcloud projects get-iam-policy juju-gce-1 ``` ### Gathering credential information You are now ready to download credentials for your chosen service account. -Here we've called the download file `juju-gce-sa.json`: +Here we've called the download file `juju-gce-1-sa.json`: ```bash -gcloud iam service-accounts keys create juju-gce-sa.json \ - --iam-account=juju-gce-sa@juju-gce-123.iam.gserviceaccount.com +gcloud iam service-accounts keys create juju-gce-1-sa.json \ + --iam-account=juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com ``` -Store this file on the Juju client (e.g. `~/.local/share/juju/juju-gce-sa.json`). +Store this file on the Juju client (e.g. `~/.local/share/juju/juju-gce-1-sa.json`). The section [Using environment variables][#using-environment-variables] below explains where this data can be stored if you wish to use the @@ -194,20 +192,20 @@ ACCOUNT_ID NAME OPEN MASTER_ACCOUNT_ID Use the account number/ID to link your project: ```bash -gcloud alpha billing projects link juju-gce-123 --billing-account 01ACD0-B3D759-187641 +gcloud alpha billing projects link juju-gce-1 --billing-account 01ACD0-B3D759-187641 ``` You can now enable the Compute Engine API for your project (this can take a few minutes to complete): ```bash -gcloud services enable compute.googleapis.com --project juju-gce-123 +gcloud services enable compute.googleapis.com --project juju-gce-1 ``` Verify by listing all currently enabled services/APIs: ```bash -gcloud services list --project juju-gce-123 +gcloud services list --project juju-gce-1 ``` ## Adding credentials @@ -218,6 +216,12 @@ management. In order to access Google GCE, you will need to add credentials to Juju. This can be done in one of three ways (as shown below). +!!! Important: + The project that gets used by Juju is determined by the service account's + credentials used to create a controller. It is therefore recommended that + the user-defined credential name strongly reflects the project name. This + is chiefly relevent in a multi-project (multi-credential) scenario. + Alternately, you can use your credentials with [Juju as a Service][jaas], where charms can be deployed using a web GUI. @@ -233,7 +237,7 @@ The command will prompt you for information that the chosen cloud needs. An example session follows: ```no-highlight -Enter credential name: juju-gce-sa +Enter credential name: juju-gce-1-sa Auth Types jsonfile @@ -241,9 +245,9 @@ Auth Types Select auth type [jsonfile]: -Enter file: ~/.local/share/juju/juju-gce-sa.json +Enter file: ~/.local/share/juju/juju-gce-1-sa.json -Credential "juju-gce-sa" added locally for cloud "google".` +Credential "juju-gce-1-sa" added locally for cloud "google".` ``` ### Using a file From 7a8b57d3efe8f0c13ea0e4d343b0be05c5ef912b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 8 Sep 2018 20:54:35 -0400 Subject: [PATCH 022/311] trivial --- src/en/clouds-gce.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index 592f39f40..278ad06bc 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -220,7 +220,7 @@ can be done in one of three ways (as shown below). The project that gets used by Juju is determined by the service account's credentials used to create a controller. It is therefore recommended that the user-defined credential name strongly reflects the project name. This - is chiefly relevent in a multi-project (multi-credential) scenario. + is chiefly relevant in a multi-project (multi-credential) scenario. Alternately, you can use your credentials with [Juju as a Service][jaas], where charms can be deployed using a web GUI. From 1ccfb4c5230c6eef92720b34b6c6c82ffa4e163a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 8 Sep 2018 21:05:08 -0400 Subject: [PATCH 023/311] edit based on GH review --- src/en/clouds-gce.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md index 278ad06bc..1a7034330 100644 --- a/src/en/clouds-gce.md +++ b/src/en/clouds-gce.md @@ -223,7 +223,8 @@ can be done in one of three ways (as shown below). is chiefly relevant in a multi-project (multi-credential) scenario. Alternately, you can use your credentials with [Juju as a Service][jaas], where -charms can be deployed using a web GUI. +charms can be deployed within a graphical environment that comes equipped with +a ready-made controller. ### Using the interactive method From 21ed8233a5aab18fb4a70a692849ee5f579bd40b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 10 Sep 2018 09:13:10 -0400 Subject: [PATCH 024/311] Revert "GCE credentials and review" --- src/en/clouds-gce.md | 338 ------------------------------------------ src/en/credentials.md | 34 ----- 2 files changed, 372 deletions(-) delete mode 100644 src/en/clouds-gce.md diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md deleted file mode 100644 index 1a7034330..000000000 --- a/src/en/clouds-gce.md +++ /dev/null @@ -1,338 +0,0 @@ -Title: Using Google GCE with Juju - -# Using Google GCE with Juju - -Juju already has knowledge of the GCE cloud, which means adding your GCE -account to Juju is quick and easy. - -You can see more specific information on Juju's GCE support (e.g. the -supported regions) by running: - -```bash -juju show-cloud google -``` - -If at any point you believe Juju's information is out of date (e.g. Google just -announced support for a new region), you can update Juju's public cloud data by -running: - -```bash -juju update-clouds -``` - -## Preparing your GCE account - -Although Juju knows how GCE works, there are a few tasks you must perform in -order to integrate your account with Juju. We give an overview of the steps -here: - - - Using the CLI tools - - Assigning user permissions - - Managing service accounts - - Gathering credential information - - Enabling the Compute Engine API - -!!! Note: - The Google [Cloud Platform Console][google-cpc] (web UI) can also be used - to complete the above steps. - -The instructions on this page make use of the Identity and Access Management -(IAM) framework to control access to your GCP account. Read Google's -[Cloud IAM][gce-iam] page for an overview. - -### Using the CLI tools - -We show how to use the [Cloud SDK tools][google-cloud-sdk-docs] from Google to -manage your GCP (Google Cloud Platform) account. The tools installation -instructions presented here are for Ubuntu/Debian. See the link above for how -to install on other platforms. - -Install the tools in this way: - -```bash -export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" -echo "deb http://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" \ - | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list -curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - -sudo apt update && sudo apt install google-cloud-sdk -``` - -Now initialise the tool: - -```bash -gcloud init -``` - -Among other things, you will be asked to enter a verification code in order to -log in to GCP. This code is acquired by following a supplied hyperlink, which, -in turn, will have you agree on the resulting page to allow Google Cloud SDK to -access your Google account. - -You will be given the choice of selecting an existing GCE project or of -creating a new one. If creating, pick a unique name to prevent the command from -exiting. If it does, re-invoke `gcloud init` and choose option [1] to -re-initialise. - -When you're done, try out the following commands (we created a project called -'juju-gce-1' during the init phase): - -```bash -gcloud components list -gcloud config list -gcloud projects list -gcloud projects describe juju-gce-1 -``` - -See the [gcloud command reference][gcloud-commands] for more help with this -tool. - -### Assigning user permissions - -Using the IAM framework, we'll be associating credentials with our project at -the *Compute Engine service account* level and not at the level of your -Google user. - -To download such credentials, however, your user (now known to the CLI tool) -must have the authorisation to do so. This is done by assigning the role of -'Service Account Key Admin' to your user (insert your project ID and your -user's email address): - -```bash -gcloud projects add-iam-policy-binding juju-gce-1 \ - --member user:javierlarin72@gmail.com \ - --role roles/iam.serviceAccountKeyAdmin -``` - -### Managing service accounts - -A project's service accounts are listed in this way: - -```bash -gcloud iam service-accounts list --project juju-gce-1 -``` - -You can create a new service account if: - - - you are having trouble identifying an existing one to use - - your project does not yet have any service accounts - - you want one dedicated to Juju - -Here, we will create a new one called 'juju-gce-1-sa': - -```bash -gcloud iam service-accounts create juju-gce-1-sa \ - --display-name "Compute Engine Juju service account" -``` - -For our example project, the list of service accounts is now: - -```no-highlight -NAME EMAIL -Compute Engine Juju service account juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com -``` - -We must now give our chosen service account enough permissions so it can do -what Juju asks of it. The roles of 'Compute Instance Admin (v1)' and 'Compute -Security Admin' are sufficient: - -```bash -gcloud projects add-iam-policy-binding juju-gce-1 \ - --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ - --role roles/compute.instanceAdmin.v1 -gcloud projects add-iam-policy-binding juju-gce-1 \ - --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ - --role roles/compute.securityAdmin -``` - -Permissions can be configured in multiple ways due to the many IAM roles -available. See upstream document [Compute Engine IAM Roles][gce-iam-roles] for -details. - -Verify the roles now assigned to both your user and your service account: - -```bash -gcloud projects get-iam-policy juju-gce-1 -``` - -### Gathering credential information - -You are now ready to download credentials for your chosen service account. -Here we've called the download file `juju-gce-1-sa.json`: - -```bash -gcloud iam service-accounts keys create juju-gce-1-sa.json \ - --iam-account=juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com -``` - -Store this file on the Juju client (e.g. `~/.local/share/juju/juju-gce-1-sa.json`). - -The section [Using environment variables][#using-environment-variables] below -explains where this data can be stored if you wish to use the -`autoload-credentials` command to add credentials to Juju. - -### Enabling the Compute Engine API - -The Compute Engine API needs to be enabled for your project but this requires -your billing account to be first linked to your project. - -Your billing (credit card) should have been set up when you registered with -GCE. To see your billing account number: - -```bash -gcloud alpha billing accounts list -``` - -Sample output: - -```no-highlight -ACCOUNT_ID NAME OPEN MASTER_ACCOUNT_ID -01ACD0-B3D759-187641 My Billing Account True -``` - -Use the account number/ID to link your project: - -```bash -gcloud alpha billing projects link juju-gce-1 --billing-account 01ACD0-B3D759-187641 -``` - -You can now enable the Compute Engine API for your project (this can take a few -minutes to complete): - -```bash -gcloud services enable compute.googleapis.com --project juju-gce-1 -``` - -Verify by listing all currently enabled services/APIs: - -```bash -gcloud services list --project juju-gce-1 -``` - -## Adding credentials - -The [Cloud credentials][credentials] page offers a full treatment of credential -management. - -In order to access Google GCE, you will need to add credentials to Juju. This -can be done in one of three ways (as shown below). - -!!! Important: - The project that gets used by Juju is determined by the service account's - credentials used to create a controller. It is therefore recommended that - the user-defined credential name strongly reflects the project name. This - is chiefly relevant in a multi-project (multi-credential) scenario. - -Alternately, you can use your credentials with [Juju as a Service][jaas], where -charms can be deployed within a graphical environment that comes equipped with -a ready-made controller. - -### Using the interactive method - -Armed with the gathered information, credentials can be added interactively: - -```bash -juju add-credential google -``` - -The command will prompt you for information that the chosen cloud needs. An -example session follows: - -```no-highlight -Enter credential name: juju-gce-1-sa - -Auth Types - jsonfile - oauth2 - -Select auth type [jsonfile]: - -Enter file: ~/.local/share/juju/juju-gce-1-sa.json - -Credential "juju-gce-1-sa" added locally for cloud "google".` -``` - -### Using a file - -A YAML-formatted file, say `mycreds.yaml`, can be used to store credential -information for any cloud. This information is then added to Juju by pointing -the `add-credential` command to the file: - -```bash -juju add-credential google -f mycreds.yaml -``` - -See section [Adding credentials from a file][credentials-adding-from-file] for -guidance on what such a file looks like. - -### Using environment variables - -With GCE you have the option of adding credentials using the following -environment variable that may already be present (and set) on your client -system: - -`CLOUDSDK_COMPUTE_REGION` - -In addition, a special variable may contain the path to a JSON-formatted file -which, in turn, contains credential information: - -`GOOGLE_APPLICATION_CREDENTIALS` - -Finally, on Linux systems, the file -`$HOME/.config/gcloud/application_default_credentials.json` may be used to -contain credential data and is parsed by the above command as part of the -scanning process. On Windows systems, the file is -`%APPDATA%\gcloud\application_default_credentials.json`. - -Add this credential information to Juju in this way: - -```bash -juju autoload-credentials -``` - -For any found credentials you will be asked which ones to use and what name to -store them under. - -For background information on this method read section -[Adding credentials from environment variables][credentials-adding-from-variables]. - -## Creating a controller - -You are now ready to create a Juju controller for cloud 'google': - -```bash -juju bootstrap google google-controller -``` - -Above, the name given to the new controller is 'google-controller'. GCE will -provision an instance to run the controller on. - -For a detailed explanation and examples of the `bootstrap` command see the -[Creating a controller][controllers-creating] page. - -## Next steps - -A controller is created with two models - the 'controller' model, which -should be reserved for Juju's internal operations, and a model named -'default', which can be used for deploying user workloads. - -See these pages for ideas on what to do next: - - - [Juju models][models] - - [Introduction to Juju Charms][charms] - - - - -[jaas]: ./getting-started.md -[controllers-creating]: ./controllers-creating.md -[models]: ./models.md -[charms]: ./charms.md -[credentials]: ./credentials.md -[credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file -[credentials-adding-from-variables]: ./credentials.md#adding-credentials-from-environment-variables -[#using-environment-variables]: #using-environment-variables -[google-cloud-sdk-docs]: https://cloud.google.com/sdk/docs/ -[gcloud-commands]: https://cloud.google.com/sdk/gcloud/reference/ -[gce-iam]: https://cloud.google.com/iam/docs/overview -[gce-iam-roles]: https://cloud.google.com/compute/docs/access/iam -[google-cpc]: https://console.cloud.google.com/ diff --git a/src/en/credentials.md b/src/en/credentials.md index b3b28e616..9d5fb9602 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -141,40 +141,6 @@ credentials: peter: auth-type: jsonfile file: ~/.config/gcloud/application_default_credentials.json - juju-gce-sa: - auth-type: oauth2 - project-id: juju-gce-123 - private-key: | - -----BEGIN PRIVATE KEY----- - MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCzTFMj0/GvhrcZ - 3B2584ZdDdsnVuHb7OYo8eqXVLYzXEkby0TMu2gM81LdGp6AeeB3nu5zwAf71YyP - erF4s0falNPIyRjDGYV1wWR+mRTbVjYUd/Vuy+KyP0u8UwkktwkP4OFR270/HFOl - Kc0rzflag8zdKzRhi7U1dlgkchbkrio148vdaoZZo67nxFVF2IY52I2qGW8VFdid - z+B9pTu2ZQKVeEpTVe5XEs3y2Y4zt2DCNu3rJi95AY4VDgVJ5f1rnWf7BwZPeuvp - 0mXLKzcvD31wEcdE6oAaGu0x0UzKvEB1mR1pPwP6qMHdiJXzkiM9DYylrMzuGL/h - VAYjhFQnAgMBAAECggEADTkKkJ10bEt1FjuJ5BYCyYelRLUMALO4RzpZrXUArHz/ - CN7oYTWykL68VIE+dNJU+Yo6ot99anC8GWclAdyTs5nYnJNbRItafYd+3JwRhU0W - vYYZqMtXs2mNMYOC+YNkibIKxYZJ4joGksTboRvJne4TN7Et/1uirr+GtLPn+W/e - umXfkpbOTDDAED8ceKKApAn6kLIW98DwHyK0rUzorOgp4DFDX9CjuWC+RG3CFGsk - oVOcDuTevJlb9Rowj1S2qYhGjuQVpVD7bcRg5zaSJKS88YbK63DCHZFpXn9JR0Fg - Vou9dnc99FdMo5vtHg7Adxh91gdqEvoaF1lHx8Var0q32QDse+spvv7K6/+7G35k - 3+1gDgF74/uMr/AVrjpoUjmGAuWweXY/vn1MVN2Uld4KPYafkOF8oTuDK5f1fu0d - cMEoKRSXQh1NCD3PZWfQt4ypYPzn9R+VBGwnBcPorytlhM9qdLxKKlaHjBlprS6Y - Be1z6FO+MqWhFlwPrKH/2uwd4QKBgQDCGESJur9OdEeroBQyYyJF7DnJ/+wHSiOr - qzvb9YW1Ddtg1iiKHHZO5FS59/D62kPaGsysCMKxI9FW53TzSxUiTaEG636C5v8J - eRdzxX04BNYNzqXbm1agBEjAa7tK8xJAjk0to4zqadUaYZog0uQs2X7Aexj2c9T/ - HQVLILHjBwKBgD/yuoLNbST+cGbuZl1s2EnTP796xPkkUm3qcUzofzmn6uivz7Qp - FMThZhHZ/Der98tra91a4e8fHaUTL5d4eCMeCL1mWXoNMnm02D/ugpEC8yDefi3T - xlM/Ed0IEVogcd49tvTvQfrhfbW/6Que/rkLKCoUlAldfIOYkS4YyyTBAoGACCpH - L9gYVi+UGEc6skfzWCew4quOfVwEFiO09/LjNhOoJ/G6cNzzqSv32H7yt0rZUeKQ - u6f+sL8F/nbsN5PwBqpnXMgpYU5gakCa2Pb05pdlfd00owFs6nxjpxyhG20QVoDm - BEZ+FhpvqZVzi2/zw2M+7s/+49dJnZXV9Cwi758CgYAquNdD4RXU96Y2OjTlOSvM - THR/zY6IPeO+kCwmBLiQC3cv59gaeOp1a93Mnapet7a2/WZPL2Al7zwnvZYsHc4z - nu1acd6D7H/9bb1YPHMNWITfCSNXerJ2idI689ShYjR2sTcDgiOQCzx+dwL9agaC - WKjypRHpiAMFbFqPT6W2uA== - -----END PRIVATE KEY----- - client-id: "206517233375074786882" - client-email: juju-gce-sa@juju-gce-123.iam.gserviceaccount.com azure: peter: auth-type: service-principal-secret From 8b6aba0e54d7fad867a7dea5aa2de9cc7f13efe7 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 10 Sep 2018 11:01:08 -0400 Subject: [PATCH 025/311] edit menu; add HTTP redirect from old page --- redirects.map | 3 +++ src/en/metadata.yaml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/redirects.map b/redirects.map index e72767007..71a70e68c 100644 --- a/redirects.map +++ b/redirects.map @@ -17,3 +17,6 @@ "~^/(?[0-9-\._]+|devel)(/|/index)?$" /${version}/en/getting-started; "~^/(?[0-9-\._]+|devel)/(?[a-zA-Z]{2})(/|/index)?$" /${version}/${language}/getting-started; "~^/(?[0-9-\._]+|devel)/en/media/(?.+)$" /en/media/${filename}; + +# Redirect help-google to clouds-gce +"~^/(?[0-9-\._]+|devel)/en/help-google/?$" /${version}/en/clouds-gce; diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 42602c879..c48043e68 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -31,7 +31,7 @@ navigation: - title: Microsoft Azure location: help-azure.md - title: Google GCE - location: help-google.md + location: clouds-gce.md - title: Oracle Compute location: help-oracle.md - title: Rackspace From 436a2c587bb4a70c33c381df02a686de1ec1c1ac Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 10 Sep 2018 11:12:10 -0400 Subject: [PATCH 026/311] Revert "Revert "GCE credentials and review"" --- src/en/clouds-gce.md | 338 ++++++++++++++++++++++++++++++++++++++++++ src/en/credentials.md | 34 +++++ 2 files changed, 372 insertions(+) create mode 100644 src/en/clouds-gce.md diff --git a/src/en/clouds-gce.md b/src/en/clouds-gce.md new file mode 100644 index 000000000..1a7034330 --- /dev/null +++ b/src/en/clouds-gce.md @@ -0,0 +1,338 @@ +Title: Using Google GCE with Juju + +# Using Google GCE with Juju + +Juju already has knowledge of the GCE cloud, which means adding your GCE +account to Juju is quick and easy. + +You can see more specific information on Juju's GCE support (e.g. the +supported regions) by running: + +```bash +juju show-cloud google +``` + +If at any point you believe Juju's information is out of date (e.g. Google just +announced support for a new region), you can update Juju's public cloud data by +running: + +```bash +juju update-clouds +``` + +## Preparing your GCE account + +Although Juju knows how GCE works, there are a few tasks you must perform in +order to integrate your account with Juju. We give an overview of the steps +here: + + - Using the CLI tools + - Assigning user permissions + - Managing service accounts + - Gathering credential information + - Enabling the Compute Engine API + +!!! Note: + The Google [Cloud Platform Console][google-cpc] (web UI) can also be used + to complete the above steps. + +The instructions on this page make use of the Identity and Access Management +(IAM) framework to control access to your GCP account. Read Google's +[Cloud IAM][gce-iam] page for an overview. + +### Using the CLI tools + +We show how to use the [Cloud SDK tools][google-cloud-sdk-docs] from Google to +manage your GCP (Google Cloud Platform) account. The tools installation +instructions presented here are for Ubuntu/Debian. See the link above for how +to install on other platforms. + +Install the tools in this way: + +```bash +export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" +echo "deb http://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" \ + | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list +curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - +sudo apt update && sudo apt install google-cloud-sdk +``` + +Now initialise the tool: + +```bash +gcloud init +``` + +Among other things, you will be asked to enter a verification code in order to +log in to GCP. This code is acquired by following a supplied hyperlink, which, +in turn, will have you agree on the resulting page to allow Google Cloud SDK to +access your Google account. + +You will be given the choice of selecting an existing GCE project or of +creating a new one. If creating, pick a unique name to prevent the command from +exiting. If it does, re-invoke `gcloud init` and choose option [1] to +re-initialise. + +When you're done, try out the following commands (we created a project called +'juju-gce-1' during the init phase): + +```bash +gcloud components list +gcloud config list +gcloud projects list +gcloud projects describe juju-gce-1 +``` + +See the [gcloud command reference][gcloud-commands] for more help with this +tool. + +### Assigning user permissions + +Using the IAM framework, we'll be associating credentials with our project at +the *Compute Engine service account* level and not at the level of your +Google user. + +To download such credentials, however, your user (now known to the CLI tool) +must have the authorisation to do so. This is done by assigning the role of +'Service Account Key Admin' to your user (insert your project ID and your +user's email address): + +```bash +gcloud projects add-iam-policy-binding juju-gce-1 \ + --member user:javierlarin72@gmail.com \ + --role roles/iam.serviceAccountKeyAdmin +``` + +### Managing service accounts + +A project's service accounts are listed in this way: + +```bash +gcloud iam service-accounts list --project juju-gce-1 +``` + +You can create a new service account if: + + - you are having trouble identifying an existing one to use + - your project does not yet have any service accounts + - you want one dedicated to Juju + +Here, we will create a new one called 'juju-gce-1-sa': + +```bash +gcloud iam service-accounts create juju-gce-1-sa \ + --display-name "Compute Engine Juju service account" +``` + +For our example project, the list of service accounts is now: + +```no-highlight +NAME EMAIL +Compute Engine Juju service account juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com +``` + +We must now give our chosen service account enough permissions so it can do +what Juju asks of it. The roles of 'Compute Instance Admin (v1)' and 'Compute +Security Admin' are sufficient: + +```bash +gcloud projects add-iam-policy-binding juju-gce-1 \ + --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ + --role roles/compute.instanceAdmin.v1 +gcloud projects add-iam-policy-binding juju-gce-1 \ + --member serviceAccount:juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com \ + --role roles/compute.securityAdmin +``` + +Permissions can be configured in multiple ways due to the many IAM roles +available. See upstream document [Compute Engine IAM Roles][gce-iam-roles] for +details. + +Verify the roles now assigned to both your user and your service account: + +```bash +gcloud projects get-iam-policy juju-gce-1 +``` + +### Gathering credential information + +You are now ready to download credentials for your chosen service account. +Here we've called the download file `juju-gce-1-sa.json`: + +```bash +gcloud iam service-accounts keys create juju-gce-1-sa.json \ + --iam-account=juju-gce-1-sa@juju-gce-1.iam.gserviceaccount.com +``` + +Store this file on the Juju client (e.g. `~/.local/share/juju/juju-gce-1-sa.json`). + +The section [Using environment variables][#using-environment-variables] below +explains where this data can be stored if you wish to use the +`autoload-credentials` command to add credentials to Juju. + +### Enabling the Compute Engine API + +The Compute Engine API needs to be enabled for your project but this requires +your billing account to be first linked to your project. + +Your billing (credit card) should have been set up when you registered with +GCE. To see your billing account number: + +```bash +gcloud alpha billing accounts list +``` + +Sample output: + +```no-highlight +ACCOUNT_ID NAME OPEN MASTER_ACCOUNT_ID +01ACD0-B3D759-187641 My Billing Account True +``` + +Use the account number/ID to link your project: + +```bash +gcloud alpha billing projects link juju-gce-1 --billing-account 01ACD0-B3D759-187641 +``` + +You can now enable the Compute Engine API for your project (this can take a few +minutes to complete): + +```bash +gcloud services enable compute.googleapis.com --project juju-gce-1 +``` + +Verify by listing all currently enabled services/APIs: + +```bash +gcloud services list --project juju-gce-1 +``` + +## Adding credentials + +The [Cloud credentials][credentials] page offers a full treatment of credential +management. + +In order to access Google GCE, you will need to add credentials to Juju. This +can be done in one of three ways (as shown below). + +!!! Important: + The project that gets used by Juju is determined by the service account's + credentials used to create a controller. It is therefore recommended that + the user-defined credential name strongly reflects the project name. This + is chiefly relevant in a multi-project (multi-credential) scenario. + +Alternately, you can use your credentials with [Juju as a Service][jaas], where +charms can be deployed within a graphical environment that comes equipped with +a ready-made controller. + +### Using the interactive method + +Armed with the gathered information, credentials can be added interactively: + +```bash +juju add-credential google +``` + +The command will prompt you for information that the chosen cloud needs. An +example session follows: + +```no-highlight +Enter credential name: juju-gce-1-sa + +Auth Types + jsonfile + oauth2 + +Select auth type [jsonfile]: + +Enter file: ~/.local/share/juju/juju-gce-1-sa.json + +Credential "juju-gce-1-sa" added locally for cloud "google".` +``` + +### Using a file + +A YAML-formatted file, say `mycreds.yaml`, can be used to store credential +information for any cloud. This information is then added to Juju by pointing +the `add-credential` command to the file: + +```bash +juju add-credential google -f mycreds.yaml +``` + +See section [Adding credentials from a file][credentials-adding-from-file] for +guidance on what such a file looks like. + +### Using environment variables + +With GCE you have the option of adding credentials using the following +environment variable that may already be present (and set) on your client +system: + +`CLOUDSDK_COMPUTE_REGION` + +In addition, a special variable may contain the path to a JSON-formatted file +which, in turn, contains credential information: + +`GOOGLE_APPLICATION_CREDENTIALS` + +Finally, on Linux systems, the file +`$HOME/.config/gcloud/application_default_credentials.json` may be used to +contain credential data and is parsed by the above command as part of the +scanning process. On Windows systems, the file is +`%APPDATA%\gcloud\application_default_credentials.json`. + +Add this credential information to Juju in this way: + +```bash +juju autoload-credentials +``` + +For any found credentials you will be asked which ones to use and what name to +store them under. + +For background information on this method read section +[Adding credentials from environment variables][credentials-adding-from-variables]. + +## Creating a controller + +You are now ready to create a Juju controller for cloud 'google': + +```bash +juju bootstrap google google-controller +``` + +Above, the name given to the new controller is 'google-controller'. GCE will +provision an instance to run the controller on. + +For a detailed explanation and examples of the `bootstrap` command see the +[Creating a controller][controllers-creating] page. + +## Next steps + +A controller is created with two models - the 'controller' model, which +should be reserved for Juju's internal operations, and a model named +'default', which can be used for deploying user workloads. + +See these pages for ideas on what to do next: + + - [Juju models][models] + - [Introduction to Juju Charms][charms] + + + + +[jaas]: ./getting-started.md +[controllers-creating]: ./controllers-creating.md +[models]: ./models.md +[charms]: ./charms.md +[credentials]: ./credentials.md +[credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file +[credentials-adding-from-variables]: ./credentials.md#adding-credentials-from-environment-variables +[#using-environment-variables]: #using-environment-variables +[google-cloud-sdk-docs]: https://cloud.google.com/sdk/docs/ +[gcloud-commands]: https://cloud.google.com/sdk/gcloud/reference/ +[gce-iam]: https://cloud.google.com/iam/docs/overview +[gce-iam-roles]: https://cloud.google.com/compute/docs/access/iam +[google-cpc]: https://console.cloud.google.com/ diff --git a/src/en/credentials.md b/src/en/credentials.md index 9d5fb9602..b3b28e616 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -141,6 +141,40 @@ credentials: peter: auth-type: jsonfile file: ~/.config/gcloud/application_default_credentials.json + juju-gce-sa: + auth-type: oauth2 + project-id: juju-gce-123 + private-key: | + -----BEGIN PRIVATE KEY----- + MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCzTFMj0/GvhrcZ + 3B2584ZdDdsnVuHb7OYo8eqXVLYzXEkby0TMu2gM81LdGp6AeeB3nu5zwAf71YyP + erF4s0falNPIyRjDGYV1wWR+mRTbVjYUd/Vuy+KyP0u8UwkktwkP4OFR270/HFOl + Kc0rzflag8zdKzRhi7U1dlgkchbkrio148vdaoZZo67nxFVF2IY52I2qGW8VFdid + z+B9pTu2ZQKVeEpTVe5XEs3y2Y4zt2DCNu3rJi95AY4VDgVJ5f1rnWf7BwZPeuvp + 0mXLKzcvD31wEcdE6oAaGu0x0UzKvEB1mR1pPwP6qMHdiJXzkiM9DYylrMzuGL/h + VAYjhFQnAgMBAAECggEADTkKkJ10bEt1FjuJ5BYCyYelRLUMALO4RzpZrXUArHz/ + CN7oYTWykL68VIE+dNJU+Yo6ot99anC8GWclAdyTs5nYnJNbRItafYd+3JwRhU0W + vYYZqMtXs2mNMYOC+YNkibIKxYZJ4joGksTboRvJne4TN7Et/1uirr+GtLPn+W/e + umXfkpbOTDDAED8ceKKApAn6kLIW98DwHyK0rUzorOgp4DFDX9CjuWC+RG3CFGsk + oVOcDuTevJlb9Rowj1S2qYhGjuQVpVD7bcRg5zaSJKS88YbK63DCHZFpXn9JR0Fg + Vou9dnc99FdMo5vtHg7Adxh91gdqEvoaF1lHx8Var0q32QDse+spvv7K6/+7G35k + 3+1gDgF74/uMr/AVrjpoUjmGAuWweXY/vn1MVN2Uld4KPYafkOF8oTuDK5f1fu0d + cMEoKRSXQh1NCD3PZWfQt4ypYPzn9R+VBGwnBcPorytlhM9qdLxKKlaHjBlprS6Y + Be1z6FO+MqWhFlwPrKH/2uwd4QKBgQDCGESJur9OdEeroBQyYyJF7DnJ/+wHSiOr + qzvb9YW1Ddtg1iiKHHZO5FS59/D62kPaGsysCMKxI9FW53TzSxUiTaEG636C5v8J + eRdzxX04BNYNzqXbm1agBEjAa7tK8xJAjk0to4zqadUaYZog0uQs2X7Aexj2c9T/ + HQVLILHjBwKBgD/yuoLNbST+cGbuZl1s2EnTP796xPkkUm3qcUzofzmn6uivz7Qp + FMThZhHZ/Der98tra91a4e8fHaUTL5d4eCMeCL1mWXoNMnm02D/ugpEC8yDefi3T + xlM/Ed0IEVogcd49tvTvQfrhfbW/6Que/rkLKCoUlAldfIOYkS4YyyTBAoGACCpH + L9gYVi+UGEc6skfzWCew4quOfVwEFiO09/LjNhOoJ/G6cNzzqSv32H7yt0rZUeKQ + u6f+sL8F/nbsN5PwBqpnXMgpYU5gakCa2Pb05pdlfd00owFs6nxjpxyhG20QVoDm + BEZ+FhpvqZVzi2/zw2M+7s/+49dJnZXV9Cwi758CgYAquNdD4RXU96Y2OjTlOSvM + THR/zY6IPeO+kCwmBLiQC3cv59gaeOp1a93Mnapet7a2/WZPL2Al7zwnvZYsHc4z + nu1acd6D7H/9bb1YPHMNWITfCSNXerJ2idI689ShYjR2sTcDgiOQCzx+dwL9agaC + WKjypRHpiAMFbFqPT6W2uA== + -----END PRIVATE KEY----- + client-id: "206517233375074786882" + client-email: juju-gce-sa@juju-gce-123.iam.gserviceaccount.com azure: peter: auth-type: service-principal-secret From bc866e70ac4a3bb245d8048453186f420da77053 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 10 Sep 2018 11:17:41 -0400 Subject: [PATCH 027/311] tweak credentials yaml file on credentials page --- src/en/credentials.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index b3b28e616..19d4a1caf 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -141,9 +141,9 @@ credentials: peter: auth-type: jsonfile file: ~/.config/gcloud/application_default_credentials.json - juju-gce-sa: + juju-gce-1-sa: auth-type: oauth2 - project-id: juju-gce-123 + project-id: juju-gce-1 private-key: | -----BEGIN PRIVATE KEY----- MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCzTFMj0/GvhrcZ From 6bee5b459143dc9b76a5dc2c19f82a7fa6a6fde4 Mon Sep 17 00:00:00 2001 From: Will Moggridge Date: Tue, 11 Sep 2018 15:17:38 +0100 Subject: [PATCH 028/311] Limit getting-started redirect to 1.25 --- redirects.map | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/redirects.map b/redirects.map index 71a70e68c..d80d26303 100644 --- a/redirects.map +++ b/redirects.map @@ -1,21 +1,24 @@ -~^/(|en/?)?$ /2.4/en/getting-started; -~^/devel/en/?$ /devel/en/getting-started; +~^/(|en/?)?$ /2.4/en/; +~^/devel/en/?$ /devel/en/; ~^en/(?.+)$ /2.4/en/${path}; # Redirect /stable to correct version -~^/stable/?$ /2.4/en/getting-started; -~^/stable/en/?$ /2.4/en/getting-started; +~^/stable/?$ /2.4/en/; +~^/stable/en/?$ /2.4/en/; ~^/stable/(?.+)$ /2.4/${path}; # Redirect pages which don't specify \en\ to the \en\ version -"~^/(?[0-9-\._]+|devel)/(?(?!en/).+)$" /${version}/en/${path}; +"~^/(?[0-9-\._]+|devel)/(?(?!en/?).+)$" /${version}/en/${path}; # Redirect pages without version or en to /en "~^/(?!([0-9-\._]+|devel|stable|master|en)/)(?.+)$" /2.4/en/${path}; -"~^/(?[0-9-\._]+|devel)(/|/index)?$" /${version}/en/getting-started; -"~^/(?[0-9-\._]+|devel)/(?[a-zA-Z]{2})(/|/index)?$" /${version}/${language}/getting-started; +# Redirect 1.25 docs index to getting-started page +"~^/1\.25(/|/index)?$" /1.25/en/getting-started; +"~^/1\.25/(?[a-zA-Z]{2})(/|/index)?$" /1.25/${language}/getting-started; + +# Redirect old media paths "~^/(?[0-9-\._]+|devel)/en/media/(?.+)$" /en/media/${filename}; # Redirect help-google to clouds-gce From c9079bf5cb5de4ce8d0518141bcc967c65b1c567 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 14:10:15 -0400 Subject: [PATCH 029/311] test --- redirects.map | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/redirects.map b/redirects.map index d80d26303..8ccc17e6f 100644 --- a/redirects.map +++ b/redirects.map @@ -1,5 +1,5 @@ ~^/(|en/?)?$ /2.4/en/; -~^/devel/en/?$ /devel/en/; +#~^/devel/en/?$ /devel/en/; ~^en/(?.+)$ /2.4/en/${path}; From 347186978d8b2eb4c03097a1eaa7534a4961dafb Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 14:32:28 -0400 Subject: [PATCH 030/311] remove 2.2 from versions file --- versions | 1 - 1 file changed, 1 deletion(-) diff --git a/versions b/versions index a46bb0667..208543ced 100644 --- a/versions +++ b/versions @@ -1,5 +1,4 @@ 2.4 2.3 -2.2 1.25 devel From 243a2797a2b8261c99843e931d9a19b89dd03d38 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 15:25:54 -0400 Subject: [PATCH 031/311] change title --- src/en/getting-started.md | 2 +- src/en/metadata.yaml | 2 +- src/en/tut-google.md | 4 ++-- src/en/tut-lxd.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/en/getting-started.md b/src/en/getting-started.md index 19ae7ea51..5cbdd511d 100644 --- a/src/en/getting-started.md +++ b/src/en/getting-started.md @@ -9,7 +9,7 @@ between the Juju client and the workload machines. The instructions on this page will show you how to get started with Juju by using the online hosted Juju controller, the Juju as a Service (JAAS) controller. If you'd prefer to test it out locally, see the -[Getting started with Juju and LXD][tut-lxd] guide. +[Using Juju locally (LXD)][tut-lxd] guide. ## JAAS diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 2cbbe569b..05e1a58a7 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -14,7 +14,7 @@ navigation: location: getting-started.md - title: What's new in 2.4 location: whats-new.md - - title: Local Juju with LXD cloud + - title: Using Juju locally (LXD) location: tut-lxd.md - title: Controllers and Models location: tut-google.md diff --git a/src/en/tut-google.md b/src/en/tut-google.md index 2728e34b4..1c3ee6620 100644 --- a/src/en/tut-google.md +++ b/src/en/tut-google.md @@ -17,8 +17,8 @@ the magic of Juju that makes it happen. !!! Note: If you already have a controller, such as the one created in the - [Getting started with Juju and LXD][tut-lxd] page, this new controller will - be seamlessly added alongside. + [Using Juju locally (LXD)][tut-lxd] page, this new controller will be + seamlessly added alongside. ## Installation diff --git a/src/en/tut-lxd.md b/src/en/tut-lxd.md index e59116d13..5a9498948 100644 --- a/src/en/tut-lxd.md +++ b/src/en/tut-lxd.md @@ -1,9 +1,9 @@ -Title: Getting started with Juju and LXD +Title: Using Juju locally (LXD) TODO: Warning: Ubuntu release versions hardcoded tutorials at the bottom may get renamed sudo is not required for lxd > 3.0.1 (edit when appropriate) -# Getting started with Juju and LXD +# Using Juju locally (LXD) This guide will get you started quickly with Juju by setting up everything you need on a single [Ubuntu 18.04 LTS][Bionic-download] (Bionic) system. It does From 7e228672da5cc9eca6da3070e326e81b9e82b4e4 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 17:20:38 -0400 Subject: [PATCH 032/311] edit menu --- src/en/metadata.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 05e1a58a7..c506e53ec 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -16,8 +16,6 @@ navigation: location: whats-new.md - title: Using Juju locally (LXD) location: tut-lxd.md - - title: Controllers and Models - location: tut-google.md - title: Sharing and Users location: tut-users.md From a6063256b98af5d9ddec0ad79c7c6e945cc7b81c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 18:26:12 -0400 Subject: [PATCH 033/311] edit menu --- src/en/metadata.yaml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index c506e53ec..724c9de20 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -1,22 +1,23 @@ navigation: - title: Introduction + children: - title: Home location: index.md - title: What is Juju? location: about-juju.md + - title: What's new in 2.4 + location: whats-new.md - - title: Quick Guides + - title: Tutorials children: - - title: Get started + - title: Getting started with Juju location: getting-started.md - - title: What's new in 2.4 - location: whats-new.md - title: Using Juju locally (LXD) location: tut-lxd.md - - title: Sharing and Users + - title: Sharing and users location: tut-users.md - title: User Guide @@ -51,7 +52,7 @@ navigation: - title: Manual location: clouds-manual.md - - title: Cloud credentials + - title: Credentials location: credentials.md - title: Juju client @@ -72,6 +73,7 @@ navigation: - title: Models location: models.md + - title: Charms location: charms.md From 988b7ad8a08d97e2640602f3107b06dad5021078 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 18:48:31 -0400 Subject: [PATCH 034/311] refactor --- src/en/credentials.md | 4 ++-- src/en/getting-started.md | 16 ++++++---------- src/en/metadata.yaml | 2 +- src/en/models.md | 4 ++-- src/en/tut-lxd.md | 6 ++---- src/en/tut-users.md | 4 ++-- 6 files changed, 15 insertions(+), 21 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 19d4a1caf..cdb63413b 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -1,10 +1,10 @@ -Title: Cloud credentials +Title: Credentials TODO: Investigate: shouldn't `model-config` have a default-credential setting? Review required Add to mycreds.yaml: cloudsigma, rackspace, and oracle. also openstack using access-key table_of_contents: True -# Cloud credentials +# Credentials In order to access your cloud, Juju needs to know how to authenticate itself. We use the term *credentials* to describe the material necessary to do this diff --git a/src/en/getting-started.md b/src/en/getting-started.md index 5cbdd511d..61e3628e7 100644 --- a/src/en/getting-started.md +++ b/src/en/getting-started.md @@ -296,11 +296,9 @@ hours of looking up configuration options or wrestling with install scripts! To discover more about what Juju can do for you, we suggest taking a look at some of the following pages of documentation: - - [Creating your own cloud controller][tut-google] - - [Creating models locally with LXD][tut-lxd] - - [Share your model with other users][share] - - [Learn more about charms and bundles][learn] - - [Find out how to customise and manage models][customise] + - [Using Juju locally (LXD)][tut-lxd] + - [Multi-user cloud][tut-users] + - [Models][models] @@ -320,11 +318,9 @@ some of the following pages of documentation: [gcedashboard]: https://console.cloud.google.com [gcecredentials]: https://console.developers.google.com/apis/credentials [install]: ./reference-install.html -[tut-lxd]: ./tut-lxd.html -[tut-google]: ./tut-google.html -[share]: ./tut-users.html -[learn]: ./charms.html -[customise]: ./models.html +[tut-lxd]: ./tut-lxd.md +[tut-users]: ./tut-users.md +[models]: ./models.md [snapcraft]: https://snapcraft.io [aws-creds]: ./help-aws.html#credentials [azure-creds]: ./help-azure.html#credentials diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 724c9de20..9d3baabea 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -17,7 +17,7 @@ navigation: location: getting-started.md - title: Using Juju locally (LXD) location: tut-lxd.md - - title: Sharing and users + - title: Multi-user cloud location: tut-users.md - title: User Guide diff --git a/src/en/models.md b/src/en/models.md index 7592bba42..50e8f64b8 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -1,8 +1,8 @@ -Title: Juju models +Title: Models TODO: Review required. Convert to abstract links -# Juju models +# Models A Juju *model* is an environment associated with a *controller* (see [Controllers](./controllers.html)). When a controller is created two models are diff --git a/src/en/tut-lxd.md b/src/en/tut-lxd.md index 5a9498948..dcce8d3c1 100644 --- a/src/en/tut-lxd.md +++ b/src/en/tut-lxd.md @@ -233,8 +233,7 @@ Juju! To continue your journey with Juju we suggest the following topics: - - [Add controllers for additional clouds][tut-cloud] - - [Share your model with other users][share] + - [Multi-user cloud][tut-users] @@ -247,5 +246,4 @@ To continue your journey with Juju we suggest the following topics: [clouds]: ./clouds.md [concepts]: ./juju-concepts.md [long-term-support]: https://wiki.ubuntu.com/LTS -[share]: ./tut-users.md -[tut-cloud]: ./tut-google.md +[tut-users]: ./tut-users.md diff --git a/src/en/tut-users.md b/src/en/tut-users.md index e311af89d..f74762299 100644 --- a/src/en/tut-users.md +++ b/src/en/tut-users.md @@ -1,8 +1,8 @@ -Title: Sharing Clouds +Title: Multi-user cloud TODO: change screenshot username from degville to newuser add link to a table showing permissions for each type of user -# Sharing Clouds +# Multi-user cloud Juju is great at deploying applications to the cloud, but it is even better when others can join in too! From 1bad07ee02386225ca7814fe623a013f81375df4 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Sep 2018 19:50:17 -0400 Subject: [PATCH 035/311] remove admonition --- src/en/credentials.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index cdb63413b..9afb2a411 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -1,6 +1,5 @@ Title: Credentials TODO: Investigate: shouldn't `model-config` have a default-credential setting? - Review required Add to mycreds.yaml: cloudsigma, rackspace, and oracle. also openstack using access-key table_of_contents: True @@ -367,11 +366,6 @@ juju add-credential --replace joe juju update-credential google joe ``` -!!! Warning: - It is not possible to update the credentials if the initial credential name - is unknown. This restriction will be removed in an upcoming release of - Juju. - #### Updating remote credentials using a different Juju user If you are unable to ascertain the original Juju username then you will need From af00737e0a8310b8ff394e158ae52025e09b0351 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Sep 2018 08:03:06 -0400 Subject: [PATCH 036/311] edit archive --- archive | 1 + 1 file changed, 1 insertion(+) diff --git a/archive b/archive index 01b935a70..4f5c4022b 100644 --- a/archive +++ b/archive @@ -6,3 +6,4 @@ 1.24 2.0 2.1 +2.2 From fd5920b7bdf3bfd6a1de0f97a6983744580d25f6 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Sep 2018 23:27:32 -0400 Subject: [PATCH 037/311] first pass --- src/en/clouds-oci.md | 327 ++++++++++++++++++++++++++++++++++++++++++ src/en/clouds.md | 5 +- src/en/credentials.md | 38 +++++ 3 files changed, 369 insertions(+), 1 deletion(-) create mode 100644 src/en/clouds-oci.md diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md new file mode 100644 index 000000000..7bdac5477 --- /dev/null +++ b/src/en/clouds-oci.md @@ -0,0 +1,327 @@ +Title: Using Oracle Cloud Infrastructure with Juju +TODO: Review required: 2.5 changes still to come + +# Using Oracle Cloud Infrastructure with Juju + +Juju has built-in support (!!!!) for [Oracle Cloud Infrastructure][oracle-oci], +Oracle's public cloud. This means that there is no need to add the Oracle cloud +to Juju. An exception to this is if you have an Oracle Compute trial account. +Both types of accounts, paid and trial, are covered here. + +This page will cover the following steps: + + 1. For trial accounts, add the Oracle cloud to Juju. + 1. Add cloud + 1. Add credentials to Juju so it can make use of your Oracle Compute account. + 1. Create the Juju controller + +## Gathering information + +Upon first login (to 'My Services URL') you will be prompted to change the +temporary password to arrive at your final password. + +Concepts +https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/concepts.htm + +- Tenancy +- Compartment + +================= + +https://cloud.oracle.com/en_US/cloud-infrastructure + +sign up + +https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm + +- SSL keypair and fingerprint +- Oracle Cloud Identifier (OCID) +https://docs.cloud.oracle.com/iaas/Content/General/Concepts/identifiers.htm + +directory: + +mkdir ~/.oci +openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 +chmod go-rwx ~/.oci/oci_api_key.pem +openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem +openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c +(last command: fingerprint) + +In the Console: +https://console.us-phoenix-1.oraclecloud.com/ + +OCID (tenancy): +ocid1.tenancy.oc1..aaaaaaaanosly647z7davq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia + +OCID (user): +ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue34d5tupearr5u7656sztwqy5twrplckzghq + +Upload the public key (under 'API Keys') + +Setting Up Your Tenancy: +https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/settinguptenancy.htm + +OCID (compartment [root]; same as the tenancy OCID): +ocid1.tenancy.oc1..aaaaaaaanosly647z7davq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia + +Add cloud: +Create a cloud file (e.g. 'oci-cloud.yaml') and replace the variables with the +corresponding values for your account. +Here we've used 'oci-test' and 'us-ashburn-1' for cloud name and cloud region respectively. +Your region is listed in the Console. + +clouds: + $CLOUD_NAME: + type: oci + auth-types: [httpsig] + regions: + $CLOUD_REGION: {} + +Now add the cloud to Juju. Use your own cloud name and cloud file: + +juju add-cloud oci-test oci-cloud.yaml + +Add credential: +Create a credential file (e.g. 'oci-creds.yaml') and replace the variables with the +corresponding values for your account: + +credentials: + $CLOUD_NAME: + default-region: $CLOUD_REGION + $CREDENTIAL_NAME: + auth-type: httpsig + fingerprint: $SSL_PUBLIC_KEY_FINGERPRINT + key: | + $SSL_PRIVATE_KEY + pass-phrase: $SSL_PRIVATE_KEY_PASSPHRASE + region: $CLOUD_REGION + tenancy: $OCID_TENANCY + user: $OCID_USER + +Add the credential to Juju. Use your own cloud name and credential file: + +juju add-credential oci-test -f oci-creds.yaml + +Creat a controller: +juju bootstrap --config compartment-id=$OCID_COMPARTMENT oci-test oci-test-controller + +## Trial accounts + +As mentioned, you will need to add your Oracle cloud to Juju if you're using a +trial account. This requires a 'REST Endpoint'. To get this, navigate to 'My +Account URL', scroll down to 'Oracle Compute Cloud Service', and click on it. +The resulting page will look similar to this: + +![REST endpoint](./media/oracle_myservices-endpoint-2.png) + +There may be multiple endpoints. In that case, trial and error may be needed +below (hint: the endpoint domain should be resolvable using DNS). + +You are now ready to use the interactive `add-cloud` command: + +```bash +juju add-cloud +``` + +Example user session: + +```no-highlight +Cloud Types + maas + manual + openstack + oracle + vsphere + +Select cloud type: oracle + +Enter a name for your oracle cloud: oracle-cloud + +Enter the API endpoint url for the cloud: +https://compute.uscom-central-1.oraclecloud.com/ + +Cloud "oracle-cloud" successfully added +You may bootstrap with 'juju bootstrap oracle-cloud' +``` + +We've called the new cloud 'oracle-cloud' and used an endpoint of +'https://compute.uscom-central-1.oraclecloud.com/'. + +Now confirm the successful addition of the cloud: + +```bash +juju clouds +``` + +Here is a partial output: + +```no-highlight +Cloud Regions Default Type Description +. +. +. +oracle 5 uscom-central-1 oracle Oracle Compute Cloud Service +oracle-cloud 0 oracle Oracle Compute Cloud Service +``` + +Cloud 'oracle' is for the built-in (for pay) service and cloud 'oracle-cloud' +is tied to your trial account. + +## Adding an OCI cloud + +Use the interactive `add-cloud` command to add your MAAS cloud to Juju's list +of clouds. You will need to supply a name you wish to call your cloud and the +unique MAAS API endpoint. + +For the manual method of adding a MAAS cloud, see below section +[Manually adding MAAS clouds][#clouds-maas-manual]. + +```bash +juju add-cloud +``` + +Example user session: + +```no-highlight +Cloud Types + maas + manual + openstack + oracle + vsphere + +Select cloud type: maas + +Enter a name for your maas cloud: maas-cloud + +Enter the API endpoint url: http://10.55.60.29:5240/MAAS + +Cloud "maas-cloud" successfully added +You may bootstrap with 'juju bootstrap maas-cloud' +``` + +We've called the new cloud 'maas-cloud' and used an endpoint of +'http://10.55.60.29:5240/MAAS'. + +Now confirm the successful addition of the cloud: + +```bash +juju clouds +``` + +Here is a partial output: + +```no-highlight +Cloud Regions Default Type Description +. +. +. +maas-cloud 0 maas Metal As A Service +``` + +### Manually adding an OCI cloud + +This example covers manually adding a MAAS cloud to Juju (see +[Adding clouds manually][clouds-adding-manually] for background information). +It also demonstrates how multiple clouds of the same type can be defined and +added. + +The manual method necessitates the use of a [YAML-formatted][yaml] +configuration file. Here is an example: + +```yaml +clouds: + devmaas: + type: maas + auth-types: [oauth1] + endpoint: http://devmaas/MAAS + testmaas: + type: maas + auth-types: [oauth1] + endpoint: http://172.18.42.10/MAAS + prodmaas: + type: maas + auth-types: [oauth1] + endpoint: http://prodmaas/MAAS +``` + +This defines three MAAS clouds and refers to them by their respective region +controllers. + +To add clouds 'devmaas' and 'prodmaas', assuming the configuration file is +`maas-clouds.yaml` in the current directory, we would run: + +```bash +juju add-cloud devmaas maas-clouds.yaml +juju add-cloud prodmaas maas-clouds.yaml +``` + +## Adding credentials + +The [Credentials][credentials] page offers a full treatment of credential +management. + +Use the interactive `add-credential` command to add your credentials to the new +cloud: + +```bash +juju add-credential maas-cloud +``` + +Example user session: + +```no-highlight +Enter credential name: maas-cloud-creds + +Using auth-type "oauth1". + +Enter maas-oauth: + +Credentials added for cloud maas-cloud. +``` + +We've called the new credential 'maas-cloud-creds'. When prompted for +'maas-oauth', you should paste your MAAS API key. + +!!! Note: + The API key will not be echoed back to the screen. + +## Creating a controller + +You are now ready to create a Juju controller for cloud 'maas-cloud': + +```bash +juju bootstrap maas-cloud maas-cloud-controller +``` + +Above, the name given to the new controller is 'maas-cloud-controller'. MAAS +will allocate a node from its pool to run the controller on. + +For a detailed explanation and examples of the `bootstrap` command see the +[Creating a controller][controllers-creating] page. + +## Next steps + +A controller is created with two models - the 'controller' model, which should +be reserved for Juju's internal operations, and a model named 'default', which +can be used for deploying user workloads. + +See these pages for ideas on what to do next: + + - [Models][models] + - [Introduction to Juju Charms][charms] + + + + +[yaml]: http://www.yaml.org/spec/1.2/spec.html +[oracle-oci]: https://maas.io +[cloudoracle]: https://cloud.oracle.com/home +[maas-manual]: ./clouds-maas-manual.md +[create-a-controller-with-constraints]: ./controllers-creating.md#create-a-controller-with-constraints +[#clouds-maas-manual]: #manually-adding-maas-clouds +[clouds-adding-manually]: ./clouds.md#adding-clouds-manually +[credentials]: ./credentials.md +[controllers-creating]: ./controllers-creating.md +[models]: ./models.md +[charms]: ./charms.md diff --git a/src/en/clouds.md b/src/en/clouds.md index 35fd22bb2..0f53f61e2 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -3,7 +3,7 @@ TODO: Bug tracking: https://bugs.launchpad.net/juju/+bug/1749302 Bug tracking: https://bugs.launchpad.net/juju/+bug/1749583 INFO: Auth types found at ~/.local/share/juju/public-clouds.yaml There is contention whether access-key can be used with keystone v3 (see https://github.com/juju/docs/issues/2868) - Needs to be updated for the new Oracle cloud (OCI) + Needs to be updated for the possible removal of the old Oracle cloud (Oracle Classic) Update: Juju is growing an authentication type for OpenStack: certificates Update: Juju is growing add-cloud for (remote) LXD table_of_contents: True @@ -29,6 +29,7 @@ how clouds are added. You can still get started by selecting your cloud here: - [Microsoft Azure][clouds-azure] - [Google GCE][clouds-google] - [Oracle Compute][clouds-oracle] + - [Oracle Cloud Infrastructure][clouds-oci] - [Rackspace][clouds-rackspace] - [Joyent][clouds-joyent] - [LXD][clouds-lxd] @@ -169,6 +170,7 @@ of adding a cloud manually. `lxd` | n/a `maas` | `oauth1` `manual` | n/a +`oci` | `httpsig` `openstack` | `access-key,userpass` `oracle` | `userpass` `rackspace` | `userpass` @@ -192,6 +194,7 @@ Here are some examples of manually adding a cloud: [clouds-azure]: ./help-azure.md [clouds-google]: ./help-google.md [clouds-oracle]: ./help-oracle.md +[clouds-oci]: ./clouds-oci.md [clouds-rackspace]: ./help-rackspace.md [clouds-joyent]: ./help-joyent.md [clouds-lxd]: ./clouds-LXD.md diff --git a/src/en/credentials.md b/src/en/credentials.md index 9afb2a411..1d77380d1 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -180,6 +180,44 @@ credentials: application-id: niftyapp subscription-id: 31fb132e-e774-49dd-adbb-d6a4e966c583 application-password: UberPassK3yz + + oci-test: + default-region: us-ashburn-1 + jlarin: + auth-type: httpsig + fingerprint: a3:57:81:9c:d2:d5:af:31:3b:73:1e:2b:a4:ae:96:ee + key: | + -----BEGIN RSA PRIVATE KEY----- + MIIEogIBAAKCAQEAoc9jtcvo49FWe3sOhS6c1ExkllNZ61vChsLmMhBCI1vMc8wu + cMpNmYK1ZA+d2Mm5YWDwn4UrSTzyaFdAIesmRljfbYMGTLznI/nfQMa1hkmplF5Q + xNPCdzs0afqfnubIyrvCKYfAsRzjCcs7C30n6PzG5WrKxzr1QNvAuvYgjd2oQuSY + nAhDgdJDkA9UwJFgI1hE8EuoxjkvmyeL76ohe78IEjMzoBBvll/Vd3d8X/hCHt4b + wkmn3B5+QzXIvYXGhaUoZrmG6V+tek2H5voJj6TswDB8rqIa1SHbY81wIkMUxbD4 + ScAq8eq2/6ETXcoBULKCjmvyqekJHjT7NngbpwIDAQABAoIBAEEggheIDSK0/UQS + EZQVYNYqMUo4HjcW5cL/PRvlY1lr92ycQAzxwC4LaArwJi49czn4lKEALp35w++v + PoboaK1j0/n2BLEaT0YxqmQeFq4INBMdqxCt0tW+pKgLUffZF/RRgiLJGwuufstQ + W2GSbF/gbgWk6B0sY85JJNebfRrb+qjp5Jz+5t5gNVzOwWWkPYoAKXPd9JHYPFAk + JCUTloYdf16lBml+nZI7EGojXtHUpdF7KyYRVfXMfxBnaWpVHvoZBk5Vk5qL/boz + N8W+YahFq9BELavYQ30CZQeWYoD2MUSCWv+WzfkER8YK5Onr+5CSU0lW9dqN6wuv + LFozUgECgYEAy9vZb+hjn3otkEFvyCGg9wmGIs9Qro3UKJI/mGKQeL7K8sd5WsA6 + mbOkIDbK71ZG+iIfxDXLzRO1ZzPjAX3cReFZ9NFRHngX9xM92UP+icIJkM6m4ImN + UcaGCZiF0LoKUTAkEw+5rpeudGcgNgaI41RKMUBLyQn5MFo3IAPaO4ECgYEAyzJN + CqB4e+qJgmc29zKsSfvuofasDTmIMnOZW2ci+tiD/qiH/eJoKHK2F5yGV6/tB2iY + kFSuzWEwu/Crl8seW6xPY+HYlGLD60ix1aRDEfR48bZqFqlIu7uowI9dp43aOmPU + 1YSgMj8UA+rVqHqrS6IX4iqGbEOuzq0a377qiycCgYA99oUQzsH5J1nSDxG68v3K + GMr8qacMZ2+lJU7PMqZXDScCxD7Opr8pGME6SW1FciQAw36EVRWtL+BjjhBcw7TA + SM7e6wCNElO2ddLGxzQHC0N9EFMIzMZ3pK/5arMRznp0Uv2kDZOSzefo2a+gvDu/ + XU9vyOtAIBft6n327TTYAQKBgEE3/OhbRzCmv8oeLNM87XW1qgtMLD72Z1OiLOfc + e6q90efr2fJQOBQ7dVywvaHpco+9L7Krq4vWlXjdL4ZCCJVuAfFSLPy7kpyzMXkc + Bvb9W9BhNz3cyd6PxdDTQFhNwbXdE2QQ9IYMHvV+62LvNInLFhVehtS7CKGHiCem + lItjAoGAdnj8nJRFQCAyIGcYk6bloohXI8ko0KLYbHfQpN9oiZa+5crEMzcFiJnR + X8rWVPCLZK5gJ56CnP8Iyoqah/hpxTUZoSaJnBb/xa7PCiMq1gBfSF8OYlCsRI0V + semYTOymUHkZyWGMIhmdn6t1S9sOy2tYjiH6HqumwirxnD5CLDk= + -----END RSA PRIVATE KEY----- + pass-phrase: "carbonbasedlifeforms" + region: us-ashburn-1 + tenancy: ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia + user: ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq joyent: peter: auth-type: userpass From dc0c46e53384ebe14301a3bf8f523f0698f1c194 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 14 Sep 2018 10:42:02 -0400 Subject: [PATCH 038/311] finish for now --- src/en/clouds-maas.md | 2 +- src/en/clouds-oci.md | 321 +++++++++++++++++++----------------------- src/en/clouds.md | 2 + src/en/credentials.md | 1 - 4 files changed, 146 insertions(+), 180 deletions(-) diff --git a/src/en/clouds-maas.md b/src/en/clouds-maas.md index cc983f246..9c7ac2998 100644 --- a/src/en/clouds-maas.md +++ b/src/en/clouds-maas.md @@ -100,7 +100,7 @@ juju add-cloud prodmaas maas-clouds.yaml ## Adding credentials -The [Cloud credentials][credentials] page offers a full treatment of credential +The [Credentials][credentials] page offers a full treatment of credential management. Use the interactive `add-credential` command to add your credentials to the new diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index 7bdac5477..7c6b814da 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -3,107 +3,107 @@ TODO: Review required: 2.5 changes still to come # Using Oracle Cloud Infrastructure with Juju -Juju has built-in support (!!!!) for [Oracle Cloud Infrastructure][oracle-oci], -Oracle's public cloud. This means that there is no need to add the Oracle cloud -to Juju. An exception to this is if you have an Oracle Compute trial account. +Juju has built-in support (!!!!) for [Oracle Cloud Infrastructure][oracle-oci] +(OCI), Oracle's public cloud. This means that there is no need to add the +Oracle cloud to Juju. An exception to this is if you are using a trial account. Both types of accounts, paid and trial, are covered here. This page will cover the following steps: - 1. For trial accounts, add the Oracle cloud to Juju. - 1. Add cloud - 1. Add credentials to Juju so it can make use of your Oracle Compute account. - 1. Create the Juju controller + 1. For trial accounts, add the OCI cloud to Juju. + 1. Add credentials to Juju so it can make use of your OCI account. + 1. Create the Juju controller. -## Gathering information +!!! Note: + Oracle's [SDK tools][oracle-oci-cli] can also be used to manage your OCI + account. -Upon first login (to 'My Services URL') you will be prompted to change the -temporary password to arrive at your final password. +## Understanding and preparing your OCI account -Concepts -https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/concepts.htm +The instructions on this page refer to certain OCI concepts. Familiarise +yourself with them by reading Oracle's [Concepts][oracle-oci-concepts] page. +The key concepts for us here are "Tenancy", "Compartment", and "OCID". -- Tenancy -- Compartment +Your Tenancy can be designed according to how you intend to use your OCI +account but there is no hard requirement to perform any configuration changes +to it in order to use it with Juju. However, for enterprise rollouts you will +most certainly need to do this for both organisational and security reasons. -================= +To organise your Tenancy and its associated compartments read Oracle's +[Setting up your Tenancy][oracle-oci-tenancy] page. -https://cloud.oracle.com/en_US/cloud-infrastructure +## Gathering information -sign up +The following bits of information need to be gathered: -https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm + - SSL keypair and fingerprint + - Oracle Cloud Identifiers (OCIDs) -- SSL keypair and fingerprint -- Oracle Cloud Identifier (OCID) -https://docs.cloud.oracle.com/iaas/Content/General/Concepts/identifiers.htm +### SSL keypair and fingerprint -directory: +An SSL keypair (private and public keys) needs to be generated on your local +system. The below list of Linux-based commands accomplish this. For a full +explanation of them, in addition to what to do on a non-Linux system, see +Oracle's [Required Keys and OCIDs][oracle-oci-ssl] page. +```bash mkdir ~/.oci openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 chmod go-rwx ~/.oci/oci_api_key.pem openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c -(last command: fingerprint) +``` -In the Console: -https://console.us-phoenix-1.oraclecloud.com/ +The last command yields the fingerprint of the private key. -OCID (tenancy): -ocid1.tenancy.oc1..aaaaaaaanosly647z7davq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia +We'll later make reference to the private key, the public key, and the +fingerprint using these variables: -OCID (user): -ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue34d5tupearr5u7656sztwqy5twrplckzghq +`$SSL_PRIVATE_KEY` +`$SSL_PUBLIC_KEY` +`$SSL_PRIVATE_KEY_FINGERPRINT` -Upload the public key (under 'API Keys') +### Oracle Cloud Identifiers (OCIDs) -Setting Up Your Tenancy: -https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/settinguptenancy.htm +OCIDs are required for the following objects: -OCID (compartment [root]; same as the tenancy OCID): -ocid1.tenancy.oc1..aaaaaaaanosly647z7davq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia + - Tenancy + - User + - Compartment -Add cloud: -Create a cloud file (e.g. 'oci-cloud.yaml') and replace the variables with the -corresponding values for your account. -Here we've used 'oci-test' and 'us-ashburn-1' for cloud name and cloud region respectively. -Your region is listed in the Console. +They are all gathered via Oracle's web [Console][oracle-oci-console]. -clouds: - $CLOUD_NAME: - type: oci - auth-types: [httpsig] - regions: - $CLOUD_REGION: {} +**Tenancy OCID** +The Tenancy OCID is found by clicking in the top-right corner user icon and +choosing the 'Tenancy: your_username' menu entry. The resulting page will +provide the information. -Now add the cloud to Juju. Use your own cloud name and cloud file: +Here, we'll assign this value to a variable so we can refer to it later: -juju add-cloud oci-test oci-cloud.yaml +`OCID_TENANCY=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` -Add credential: -Create a credential file (e.g. 'oci-creds.yaml') and replace the variables with the -corresponding values for your account: +**User OCID** +The User OCID is found by clicking in the top-left menu and choosing 'Identity' +and then 'Users'. The resulting page will provide the information. -credentials: - $CLOUD_NAME: - default-region: $CLOUD_REGION - $CREDENTIAL_NAME: - auth-type: httpsig - fingerprint: $SSL_PUBLIC_KEY_FINGERPRINT - key: | - $SSL_PRIVATE_KEY - pass-phrase: $SSL_PRIVATE_KEY_PASSPHRASE - region: $CLOUD_REGION - tenancy: $OCID_TENANCY - user: $OCID_USER +Again, we'll assign this to a variable: -Add the credential to Juju. Use your own cloud name and credential file: +`OCID_USER=ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq` -juju add-credential oci-test -f oci-creds.yaml +**Compartment OCID** +The Compartment OCID is found on the same page but in the sub-menu +'Compartments': -Creat a controller: -juju bootstrap --config compartment-id=$OCID_COMPARTMENT oci-test oci-test-controller +`OCID_COMPARTMENT=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` + +Notice that the Tenancy and Compartment values are identical. This is because, +in this example, we decided to use the compartment provided to us by default +(the *root Compartment*). If you created a new compartment at the "Preparing +your OCI account" step then your values should be different. + +### Upload the public key + +Upload the public key (under 'API Keys') ## Trial accounts @@ -117,7 +117,12 @@ The resulting page will look similar to this: There may be multiple endpoints. In that case, trial and error may be needed below (hint: the endpoint domain should be resolvable using DNS). -You are now ready to use the interactive `add-cloud` command: +Use the interactive `add-cloud` command to add your OCI cloud to Juju's list +of clouds. You will need to supply a name you wish to call your cloud and +!!!!!! + +For the manual method of adding an OCI cloud, see below section +[Manually adding an OCI cloud][#clouds-oci-manual]. ```bash juju add-cloud @@ -127,82 +132,28 @@ Example user session: ```no-highlight Cloud Types + lxd maas manual + oci openstack - oracle + oracle !!!!!!!!!!!! vsphere -Select cloud type: oracle - -Enter a name for your oracle cloud: oracle-cloud - -Enter the API endpoint url for the cloud: -https://compute.uscom-central-1.oraclecloud.com/ - -Cloud "oracle-cloud" successfully added -You may bootstrap with 'juju bootstrap oracle-cloud' -``` - -We've called the new cloud 'oracle-cloud' and used an endpoint of -'https://compute.uscom-central-1.oraclecloud.com/'. - -Now confirm the successful addition of the cloud: - -```bash -juju clouds -``` - -Here is a partial output: - -```no-highlight -Cloud Regions Default Type Description -. -. -. -oracle 5 uscom-central-1 oracle Oracle Compute Cloud Service -oracle-cloud 0 oracle Oracle Compute Cloud Service -``` - -Cloud 'oracle' is for the built-in (for pay) service and cloud 'oracle-cloud' -is tied to your trial account. - -## Adding an OCI cloud +Select cloud type: oci -Use the interactive `add-cloud` command to add your MAAS cloud to Juju's list -of clouds. You will need to supply a name you wish to call your cloud and the -unique MAAS API endpoint. +Enter a name for your oci cloud: oci-test -For the manual method of adding a MAAS cloud, see below section -[Manually adding MAAS clouds][#clouds-maas-manual]. +Enter region name: us-ashburn-1 -```bash -juju add-cloud -``` +Enter another region? (y/N): N -Example user session: +Cloud "oci-cloud" successfully added -```no-highlight -Cloud Types - maas - manual - openstack - oracle - vsphere - -Select cloud type: maas - -Enter a name for your maas cloud: maas-cloud - -Enter the API endpoint url: http://10.55.60.29:5240/MAAS - -Cloud "maas-cloud" successfully added -You may bootstrap with 'juju bootstrap maas-cloud' +You may need to `juju add-credential oci-test' if your cloud needs additional credentials +then you can bootstrap with 'juju bootstrap oci-test' ``` -We've called the new cloud 'maas-cloud' and used an endpoint of -'http://10.55.60.29:5240/MAAS'. - Now confirm the successful addition of the cloud: ```bash @@ -216,86 +167,96 @@ Cloud Regions Default Type Description . . . -maas-cloud 0 maas Metal As A Service +oci-test 1 us-ashburn-1 oci ``` ### Manually adding an OCI cloud -This example covers manually adding a MAAS cloud to Juju (see +This example covers manually adding an OCI cloud to Juju (see [Adding clouds manually][clouds-adding-manually] for background information). -It also demonstrates how multiple clouds of the same type can be defined and -added. The manual method necessitates the use of a [YAML-formatted][yaml] configuration file. Here is an example: ```yaml clouds: - devmaas: - type: maas - auth-types: [oauth1] - endpoint: http://devmaas/MAAS - testmaas: - type: maas - auth-types: [oauth1] - endpoint: http://172.18.42.10/MAAS - prodmaas: - type: maas - auth-types: [oauth1] - endpoint: http://prodmaas/MAAS + oci-test: + type: oci + auth-types: [httpsig] + regions: + us-ashburn-1: {} ``` -This defines three MAAS clouds and refers to them by their respective region -controllers. +Here we've used 'oci-test' and 'us-ashburn-1' for cloud name and cloud region +respectively. Your region is listed in the Console. -To add clouds 'devmaas' and 'prodmaas', assuming the configuration file is -`maas-clouds.yaml` in the current directory, we would run: +To add cloud 'oci-test', assuming the configuration file is `oci-cloud.yaml` in +the current directory, we would run: ```bash -juju add-cloud devmaas maas-clouds.yaml -juju add-cloud prodmaas maas-clouds.yaml +juju add-cloud oci-test oci-cloud.yaml ``` ## Adding credentials -The [Credentials][credentials] page offers a full treatment of credential +The [Cloud credentials][credentials] page offers a full treatment of credential management. -Use the interactive `add-credential` command to add your credentials to the new -cloud: +In order to access Oracle OCI, you will need to add credentials to Juju. This +can be done in one of two ways (as shown below). -```bash -juju add-credential maas-cloud -``` +Alternately, you can use your credentials with [Juju as a Service][jaas], where +charms can be deployed within a graphical environment that comes equipped with +a ready-made controller. -Example user session: +### Using the interactive method -```no-highlight -Enter credential name: maas-cloud-creds +Armed with the gathered information, credentials can be added interactively +with the command `juju add-credential oci-test`. However, due to the private +SSL key that needs to be provided this method is not recommended. Use the file +method outlined next. -Using auth-type "oauth1". +### Using a file -Enter maas-oauth: +A YAML-formatted file, say `mycreds.yaml`, can be used to store credential +information for any cloud. The credential file in this example would be based +on the following (replace the variables with your own values): -Credentials added for cloud maas-cloud. +```no-highlight +credentials: + $CLOUD_NAME: + default-region: $CLOUD_REGION + $CREDENTIAL_NAME: + auth-type: httpsig + fingerprint: $SSL_PUBLIC_KEY_FINGERPRINT + key: | + $SSL_PRIVATE_KEY + pass-phrase: $SSL_PRIVATE_KEY_PASSPHRASE + region: $CLOUD_REGION + tenancy: $OCID_TENANCY + user: $OCID_USER ``` -We've called the new credential 'maas-cloud-creds'. When prompted for -'maas-oauth', you should paste your MAAS API key. +See section [Adding credentials from a file][credentials-adding-from-file] for +guidance on what such a file looks like. -!!! Note: - The API key will not be echoed back to the screen. +This information is then added to Juju by pointing the `add-credential` +command to the file: + +```bash +juju add-credential oci-test -f mycreds.yaml +``` ## Creating a controller -You are now ready to create a Juju controller for cloud 'maas-cloud': +You are now ready to create a Juju controller for cloud 'oci-test': ```bash -juju bootstrap maas-cloud maas-cloud-controller +juju bootstrap --config compartment-id=$OCID_COMPARTMENT oci-test oci-test-controller ``` -Above, the name given to the new controller is 'maas-cloud-controller'. MAAS -will allocate a node from its pool to run the controller on. +Above, the name given to the new controller is 'oci-test-controller'. OCI +will provision an instance to run the controller on. For a detailed explanation and examples of the `bootstrap` command see the [Creating a controller][controllers-creating] page. @@ -315,13 +276,17 @@ See these pages for ideas on what to do next: [yaml]: http://www.yaml.org/spec/1.2/spec.html -[oracle-oci]: https://maas.io -[cloudoracle]: https://cloud.oracle.com/home -[maas-manual]: ./clouds-maas-manual.md -[create-a-controller-with-constraints]: ./controllers-creating.md#create-a-controller-with-constraints -[#clouds-maas-manual]: #manually-adding-maas-clouds +[oracle-oci]: https://cloud.oracle.com/en_US/cloud-infrastructure +[oracle-oci-concepts]: https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/concepts.htm +[oracle-oci-ssl]: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm +[oracle-oci-tenancy]: https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/settinguptenancy.htm +[oracle-oci-cli]: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdks.htm +[oracle-oci-console]: https://console.us-phoenix-1.oraclecloud.com/ +[#clouds-oci-manual]: #manually-adding-an-oci-cloud [clouds-adding-manually]: ./clouds.md#adding-clouds-manually [credentials]: ./credentials.md +[jaas]: ./getting-started.md +[credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file [controllers-creating]: ./controllers-creating.md [models]: ./models.md [charms]: ./charms.md diff --git a/src/en/clouds.md b/src/en/clouds.md index 0f53f61e2..071880d7f 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -184,6 +184,7 @@ relative path to the file: Here are some examples of manually adding a cloud: - [Manually adding MAAS clouds][clouds-maas-manual] + - [Manually adding an OCI cloud][clouds-oci-manual] - [Manually adding an OpenStack cloud][clouds-openstack-manual] - [Manually adding a vSphere cloud][clouds-vsphere-manual] @@ -208,5 +209,6 @@ Here are some examples of manually adding a cloud: [controllers-creating-include-config]: ./controllers-creating.md#passing-a-cloud-specific-setting [clouds-maas-manual]: ./clouds-maas.md#manually-adding-maas-clouds +[clouds-oci-manual]: ./clouds-oci.md#manually-adding-an-oci-cloud [clouds-openstack-manual]: ./help-openstack.md#manually-adding-an-openstack-cloud [clouds-vsphere-manual]: ./help-vmware.md#manually-adding-a-vsphere-cloud diff --git a/src/en/credentials.md b/src/en/credentials.md index 1d77380d1..fcded22a1 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -180,7 +180,6 @@ credentials: application-id: niftyapp subscription-id: 31fb132e-e774-49dd-adbb-d6a4e966c583 application-password: UberPassK3yz - oci-test: default-region: us-ashburn-1 jlarin: From 7e15ec7c8a0fb0e1b3cebfe167b75629068c72ee Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 14 Sep 2018 11:42:25 -0400 Subject: [PATCH 039/311] trivial --- src/en/clouds-oci.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index 7c6b814da..e95d36e4e 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -48,13 +48,13 @@ Oracle's [Required Keys and OCIDs][oracle-oci-ssl] page. ```bash mkdir ~/.oci -openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 -chmod go-rwx ~/.oci/oci_api_key.pem -openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem -openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c +openssl genrsa -out ~/.oci/oci_ssl_key_private.pem -aes128 2048 +chmod go-rwx ~/.oci/oci_ssl_key_private.pem +openssl rsa -pubout -in ~/.oci/oci_ssl_key_private.pem -out ~/.oci/oci_api_key_public.pem +openssl rsa -pubout -outform DER -in ~/.oci/oci_ssl_key_private.pem | openssl md5 -c ``` -The last command yields the fingerprint of the private key. +The last command prints the fingerprint of the private key to the screen. We'll later make reference to the private key, the public key, and the fingerprint using these variables: From 965764ae3dec7591e19563e778b4fa17a0f30c2d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 14 Sep 2018 11:47:18 -0400 Subject: [PATCH 040/311] trivial --- src/en/clouds-oci.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index e95d36e4e..ff7fb200a 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -42,19 +42,21 @@ The following bits of information need to be gathered: ### SSL keypair and fingerprint An SSL keypair (private and public keys) needs to be generated on your local -system. The below list of Linux-based commands accomplish this. For a full -explanation of them, in addition to what to do on a non-Linux system, see -Oracle's [Required Keys and OCIDs][oracle-oci-ssl] page. +system. It will be used to contact Oracle's API. A "fingerprint" of the private +key will be needed to identify that key. The below list of Linux-based commands +accomplish all this. For a full explanation of them, in addition to what to do +on a non-Linux system, see Oracle's [Required Keys and OCIDs][oracle-oci-ssl] +page. ```bash mkdir ~/.oci openssl genrsa -out ~/.oci/oci_ssl_key_private.pem -aes128 2048 chmod go-rwx ~/.oci/oci_ssl_key_private.pem -openssl rsa -pubout -in ~/.oci/oci_ssl_key_private.pem -out ~/.oci/oci_api_key_public.pem +openssl rsa -pubout -in ~/.oci/oci_ssl_key_private.pem -out ~/.oci/oci_ssl_key_public.pem openssl rsa -pubout -outform DER -in ~/.oci/oci_ssl_key_private.pem | openssl md5 -c ``` -The last command prints the fingerprint of the private key to the screen. +The last command will print the fingerprint of the private key to your screen. We'll later make reference to the private key, the public key, and the fingerprint using these variables: From 3c72eb9a647fdb3bcf61a0fdec17e76e9b0ccad2 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 17 Sep 2018 09:00:57 -0400 Subject: [PATCH 041/311] change sentence --- src/en/clouds-lxd-resources.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index 50838aa08..f4db0447f 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -50,8 +50,8 @@ containers becoming unavailable. The following caveats apply: - - The controller must reside on a cluster node. This will no longer be the - case starting with v.2.5 of Juju. + - The controller must be created locally to a cluster node. This will no + longer be the case starting with v.2.5 of Juju. - Each cluster node must have a network bridge that is connected to LXD. This is to allow the containers to communicate with the controller. From 728888b9314f9e3625fc30eba4b0394c9464616c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 18 Sep 2018 10:48:48 -0400 Subject: [PATCH 042/311] start --- src/en/clouds-lxd-advanced.md | 160 +++++++++++++++++++++++++++++++++ src/en/clouds-lxd-resources.md | 1 + src/en/clouds.md | 2 +- 3 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 src/en/clouds-lxd-advanced.md diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md new file mode 100644 index 000000000..f3ae35c61 --- /dev/null +++ b/src/en/clouds-lxd-advanced.md @@ -0,0 +1,160 @@ +Title: Using LXD with Juju - advanced + +# Using LXD with Juju - advanced + +This page is dedicated to more advanced topics related to using LXD with Juju. +The main page is [Using LXD with Juju][clouds-lxd]. + +The topics presented here are: + + - Adding a remote LXD cloud + +## Adding a remote LXD cloud + +The traditional way of using LXD with Juju is by having both the Juju client +and the LXD daemon local to each other. However, since `v.2.5` Juju supports +connecting to a remote LXD daemon. + +Use the interactive `add-cloud` command to add your LXD cloud to Juju's list +of clouds. You will need to supply a name you wish to call your cloud and the +unique LXD API endpoint. + +For the manual method of adding a LXD cloud, see below section +[Manually adding a LXD cloud][#clouds-lxd-manual]. + +```bash +juju add-cloud +``` + +Example user session: + +```no-highlight +Cloud Types + + lxd + maas + manual + oci + openstack + oracle + vsphere + +Select cloud type: lxd + +Enter a name for your lxd cloud: lxd-remote + +Enter the API endpoint url for the remote LXD server: https://10.55.60.244:8443 +Auth Types + certificate + +Select one or more auth types separated by commas [certificate]: + +Enter region [default]: + +Enter the API endpoint url for the region [use cloud api url]: + +Enter another region? (y/N): n + +Cloud "lxd-remote" successfully added + +You may need to `juju add-credential lxd-remote' if your cloud needs additional credentials +Then you can bootstrap with 'juju bootstrap lxd-remote' +``` + +!!! Important: + The remote LXD server needs to be available over the network. This is + specified with `lxd init` on the remote host. + +Now confirm the successful addition of the cloud: + +```bash +juju clouds +``` + +Here is a partial output: + +```no-highlight +Cloud Regions Default Type Description +. +. +. +lxd-remote 1 default lxd LXD Container Hypervisor +``` + +### Manually adding a LXD cloud + +This covers manually adding a LXD cloud to Juju (see +[Adding clouds manually][clouds-adding-manually] for background information). + +The manual method necessitates the use of a [YAML-formatted][yaml] +configuration file. Here is an example: + +```yaml +clouds: + lxd-remote-manual: + type: lxd + auth-types: [certificate] + endpoint: 10.55.60.244 +``` + +<--! test if 'interactive' is required in the above --> + +We've call the cloud 'lxd-remote-manual' and the endpoint is the IP address of +the remote LXD host. + +To add cloud 'lxd-remote-manual', assuming the configuration file is +`lxd-cloud.yaml` in the current directory, we would run: + +```bash +juju add-cloud lxd-remote-manual lxd-cloud.yaml +``` + +## Adding credentials + +As opposed to a local LXD cloud, credentials need to be added prior to creating +a controller for a remote one. + +The [Cloud credentials][credentials] page offers a full treatment of credential +management. + +Use the interactive `add-credential` command to add your credentials to the new +cloud. The 'certificate' auth type requires you to gather the LXD server +certificate and both the LXD client certificate and key. The client in this +context is Juju. + +```bash +juju add-credential lxd-remote +``` + +Example user session: + +```no-highlight +Enter credential name: lxd-remote-creds-cert + +Auth Types + certificate + interactive + +Select auth type [interactive]: certificate + +Enter the path to the PEM-encoded LXD server certificate file: server.crt + +Enter the path to the PEM-encoded LXD client certificate file: .local/share/juju/lxd/client.crt +Enter the path to the PEM-encoded LXD client key file: .local/share/juju/lxd/client.key +Credential "lxd-remote-creds-cert" added locally for cloud "lxd-remote". +``` + +We've called the new credential 'lxd-remote-creds'. When prompted for +'', you should paste your MAAS API key. + +!!! Note: + The API key will not be echoed back to the screen. + + + +[yaml]: http://www.yaml.org/spec/1.2/spec.html +[clouds-lxd]: ./clouds-LXD +[#clouds-lxd-manual]: #manually-adding-a-lxd-cloud +[controllers-creating]: ./controllers-creating.md +[clouds-adding-manually]: ./clouds.md#adding-clouds-manually +[credentials]: ./credentials.md diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index 50838aa08..a90d7d80d 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -1,5 +1,6 @@ Title: Additional LXD resources TODO: Test certificate access + Move clustering to clouds-lxd-advanced table_of_contents: True # Additional LXD resources diff --git a/src/en/clouds.md b/src/en/clouds.md index 35fd22bb2..28a131c25 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -166,7 +166,7 @@ of adding a cloud manually. `ec2` | `access-key` `gce` | `jsonfile,oauth2` `joyent` | `userpass` -`lxd` | n/a +`lxd` | n/a, `certificate` (`v.2.5`) `maas` | `oauth1` `manual` | n/a `openstack` | `access-key,userpass` From 0176a8260947fd64ddcb2609a5fda1b03d0d9699 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 19 Sep 2018 09:36:30 -0400 Subject: [PATCH 043/311] add zones --- src/en/charms-deploying-advanced.md | 40 +++++++++++++++++++++-------- src/en/clouds-lxd-resources.md | 7 +++++ 2 files changed, 36 insertions(+), 11 deletions(-) diff --git a/src/en/charms-deploying-advanced.md b/src/en/charms-deploying-advanced.md index 2fb0b4adc..662e7167e 100644 --- a/src/en/charms-deploying-advanced.md +++ b/src/en/charms-deploying-advanced.md @@ -98,12 +98,21 @@ Machine State DNS Inst id Series AZ Message ``` The above works well with `deploy` and `add-unit` as will be shown below. As -for `bootstrap` the `--to` option is limited to pointing to a MAAS node. -Assuming a MAAS cloud has been added and is called 'maas-prod' you can -therefore do this: +for `bootstrap` the `--to` option is limited to either pointing to a MAAS node +or, starting in `v.2.5`, to a LXD cluster node. + +Assuming a MAAS cloud named 'maas-prod' exists and has a node called +'node2.maas': ```bash -juju bootstrap maas-prod --to .maas +juju bootstrap maas-prod --to node2.maas +``` + +Assuming a LXD cluster cloud named 'lxd-cluster' exists and has a node called +'node3': + +```bash +juju bootstrap lxd-cluster --to node3 ``` ### deploy --to @@ -140,13 +149,14 @@ second case, MongoDB is deployed to a new container on existing machine '25'. In the third case, nginx is deployed to existing container '3' on existing machine '24'. -Some clouds support special arguments to the `--to` option, where instead of -a machine you can specify a zone or, in the case of MAAS, an underlying -physical (or virtual) machine: +Some clouds support special arguments to the `--to` option, where instead of a +machine you can specify a zone. In the case of MAAS or a LXD cluster a node can +be specified: ```bash juju deploy mysql --to zone=us-east-1a -juju deploy mediawiki --to host.mass +juju deploy mediawiki --to node1.maas +juju deploy mariadb --to node1.lxd ``` ### add-unit --to @@ -161,13 +171,21 @@ A comma separated list of directives can be provided to cater for the case where more than one unit is being added: ```bash -juju add-unit rabbitmq-server -n 4 --to zone=us-west-1a,zone=us-east-1b juju add-unit rabbitmq-server -n 3 --to host1.maas,host2.maas,host3.maas ``` If the number of values is less than the number of requested units the -remaining units, as per normal behaviour, will be deployed to new machines. Any -surplus values are ignored. +remaining units, as per normal behaviour, will be deployed to new machines: + +```bash +juju add-unit rabbitmq-server -n 4 --to zone=us-west-1a,zone=us-east-1b +``` + +Any surplus values are ignored: + +```bash +juju add-unit rabbitmq-server -n 2 --to node1.lxd,node2.lxd,node3.lxd +``` The `add-unit` command is often associated with scaling out. See the [Scaling applications][charms-scaling] page for information on that topic. diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index f4db0447f..ef9aaac77 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -1,5 +1,6 @@ Title: Additional LXD resources TODO: Test certificate access + bug tracking: https://bugs.launchpad.net/juju/+bug/1793291 table_of_contents: True # Additional LXD resources @@ -61,6 +62,11 @@ cluster and any subsequent node will *join* the cluster. Once the cluster is set up a controller can be created, as normal, on any of the cluster nodes (e.g. `juju bootstrap localhost lxd-cluster`). +In `v.2.5` specific cluster nodes can be targeted with the commands +`bootstrap`, `deploy`, and `add-unit`. See +[Deploying to specific machines][deploying-to-specific-machines] for how to do +this. + !!! Warning: The cluster-creation process will remove any existing containers. In a Juju context, this implies that you cannot initialise a cluster *after* having @@ -203,3 +209,4 @@ assistance with the daemon. See upstream documentation for [logs]: ./troubleshooting-logs.md [credentials]: ./credentials.md [users-creating]: ./users-creating.md +[deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines From 317ba421e1c3a8dadaf3204a49b2219679da70a3 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 19 Sep 2018 10:32:04 -0400 Subject: [PATCH 044/311] update release notes --- src/en/reference-release-notes.md | 58 +++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index 6e9a7ca27..a939264f3 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -377,6 +377,64 @@ release notes for the 1.x series are available [here][release-notes-1]. To learn more about Juju visit [https://jujucharms.com][upstream-juju]. +^# Juju 2.3.9 + + The Juju team is proud to release Juju 2.3.9! + + This release is a bugfix release for Juju 2.3 which also adds support for new AWS instance types. + + ## Notable fixes + + - [LP #1770437](https://bugs.launchpad.net/juju/+bug/1770437) - juju-introspection.sh is full of bashisms, the introspection functions now use underscores to separate words, i.e. `juju-goroutines` -> `juju_goroutines` + - [LP #1733266](https://bugs.launchpad.net/juju/+bug/17733266) - Autodetection of subnets prevents bootstrap when there are duplicate subnet ranges + - [LP #1790647](https://bugs.launchpad.net/juju/+bug/1790647) - Refresh support for new aws instance types + - [LP #1789211](https://bugs.launchpad.net/juju/+bug/1789211) - Can't close/open ports without external network + + Additional bugs fixed can be found in the + [milestone page](https://launchpad.net/juju/2.3/2.3.9). + + ## How do I get it? + + The best way to get your hands on this release of Juju is to install it as a snap package: + + sudo snap install juju --classic --channel=2.3/stable + + Other packages are available for a variety of platforms: + + **Using a PPA** + To install the most recent stable version using a PPA: + + sudo add-apt-repository -yu ppa:juju/2.3 + sudo apt install juju + + **macOS** + Install Juju on macOS with Homebrew. Simply enter the following into a terminal: + + brew install juju + + And upgrade Juju with the following: + + brew upgrade juju + + **Windows** + A Windows installer is available for Juju and can be found here: + + [juju-setup-2.3.9-signed.exe](https://launchpad.net/juju/2.3/2.3.9/+download/juju-setup-2.3.9-signed.exe) ([md5](https://launchpad.net/juju/2.3/2.3.9/+download/juju-setup-2.3.9-signed.exe/+md)) + + Those subscribed to a snap channel should be automatically upgraded. If you’re + using the PPA or homebrew, you should see an upgrade available. + + ## Feedback appreciated. + + We encourage everyone to let us know how you're using Juju. You can send us a + message on Twitter using `#jujucharms`, join us in the freenode IRC channel + `#juju`, or subscribe to the [Juju Discourse forum][juju-discourse-forum]. + + ## More information + + To learn more about Juju visit + [https://jujucharms.com](https://jujucharms.com). + ^# Juju 2.3.8 Juju 2.3.8 is the exciting new release of Juju, the first to provide full From b7fac9b63a1cce3a0c934e97f94b8078773c38d9 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 20 Sep 2018 04:56:22 -0400 Subject: [PATCH 045/311] add keys --- src/en/controllers-config.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index 245ba450f..a494019db 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -77,6 +77,8 @@ identity-public-key | string | | | Se identity-url | string | | | Sets the URL of the identity manager. Feature not yet implemented. max-logs-age | string | 72h | 72h, etc. | Sets the maximum age for log entries before they are pruned, in human-readable time format max-logs-size | string | 4G | 400M, 5G, etc. | Sets the maximum size for the log collection, in human-readable memory format +max-prune-txn-batch-size | integer | 1e+06 | 100000, 1e+05, etc. | Sets the maximum number of database transaction records to be pruned during each cleanup pass. +max-prune-txn-passes | integer | 100 | | Sets the maximum number of passes to make during each automatic hourly database transaction record cleanup procedure. max-txn-log-size | string | 10M | 100M, 1G, etc. | Sets the maximum size for the capped txn log collection, in human-readable memory format mongo-memory-profile | string | low | low/default | Sets whether MongoDB uses the least possible memory or the default MongoDB memory profile network | string | | | An OpenStack network UUID. From 724c5ff24a8b9508dca06ff0fc587ba4829f8a69 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 20 Sep 2018 05:41:39 -0400 Subject: [PATCH 046/311] add key --- src/en/controllers-config.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index a494019db..ecc29def6 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -70,6 +70,7 @@ bootstrap-timeout | integer | 600 | | Ho bootstrap-retry-delay | integer | 5 | | How long in seconds to wait between connection attempts to a controller bootstrap-address-delay | integer | 10 | | How often in seconds to refresh controller addresses from the API server ca-cert | string | | | The certificate of the CA that signed the controller's CA certificate, in PEM format +charmstore-url | string | | URL | Replaces the internal Charm Store URL of https://api.jujucharms.com/charmstore with a custom one. controller-uuid | string | | | The key for the UUID of the controller juju-ha-space | string | | | The name of a network space used used for MongoDB replica-set communication in a controller HA context. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). juju-mgmt-space | string | | | The name of a network space used by Juju agents to communicate with controllers. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). From 9510d57e061b8a33c6ad3e7c51b15c359e8edd6a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 20 Sep 2018 08:14:30 -0400 Subject: [PATCH 047/311] reword; real-time keys --- src/en/controllers-config.md | 44 ++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index ecc29def6..7b51cd807 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -5,6 +5,7 @@ TODO: Check accuracy of key table (https://github.com/juju/juju/blob/ec89c99e51f ReadOnlyMethods updated from https://github.com/juju/juju/blob/2.3/apiserver/observer/auditfilter.go#L130 Include ability to set configuration key:value pairs by file Show how to use spaces 'juju-mgmt-space' and 'juju-ha-space' (wth 'juju bootstrap' and 'juju enable-ha') + Reformat table: monospace the key names, new column for RT table_of_contents: True # Configuring controllers @@ -30,37 +31,37 @@ dynamically set by Juju. ## Setting values -To set a key's value use the `--config` option during the controller creation -process (see [Creating a controller][controllers-creating]). For example, to -create and configure a cloud named 'lxd': +A key can be assigned a value during controller-creation time or post-creation +time. The vast majority of keys are set in the former way. + +To set a key at controller-creation time the `--config` option is used. For +example: ```bash -juju bootstrap --config bootstrap-timeout=700 lxd +juju bootstrap --config bootstrap-timeout=700 localhost lxd ``` -In general, once a controller is created, all its settings become immutable. -Exceptions to this rule are three of the keys related to audit logging: +See [Creating a controller][controllers-creating] for examples on +controller creation. + +To set a key at post-creation time the `controller-config` command is used. For +example: - - auditing-enabled - - audit-log-capture-args - - audit-log-exclude-methods - -!!! Note: - The `--config` option may also be used to configure the 'default' model. - In addition, the `model-default` option can usually always be used in place - of the `--config` option. See [Configuring models][models-config] for more - information on how models get configured and how these two options differ. +```bash +juju controller-config -c aws max-prune-txn-batch-size=1.2e+06 max-prune-txn-passes=120 +``` ## List of controller keys -This table lists all the controller keys which may be assigned a value. +This table lists all the controller keys. Those keys that can be assigned in +real-time (post-bootstrap) is tagged with **[RT]**. | Key | Type | Default | Valid values | Purpose | |:---------------------------|---------|----------|--------------------------|:---------| api-port | integer | 17070 | | The port to use for connecting to the API -auditing-enabled | bool | false | false/true | Sets whether audit logging is enabled. Can be toggled for an existing controller. -audit-log-capture-args | bool | false | false/true | Sets whether the audit log will contain the arguments passed to API methods. Can be toggled for an existing controller. -audit-log-exclude-methods | string | ReadOnlyMethods | [Some.Method,...] | What information to exclude from the audit log. Can be set for an existing controller. See [additional info][#excluding-information-audit-log]. +auditing-enabled **[RT]** | bool | true | false/true | Sets whether audit logging is enabled. Can be toggled for an existing controller. +audit-log-capture-args **[RT]** | bool | false | false/true | Sets whether the audit log will contain the arguments passed to API methods. Can be toggled for an existing controller. +audit-log-exclude-methods **[RT]** | string | ReadOnlyMethods | [Some.Method,...] | What information to exclude from the audit log. Can be set for an existing controller. See [additional info][#excluding-information-audit-log]. audit-log-max-backups | integer | 10 | | The maximum number of backup audit log files to keep. audit-log-max-size | integer | 300 | | The maximum size for an audit log file (units: MiB). autocert-dns-name | string | | | Sets the DNS name of the controller. If a client connects to this name, an official certificate will be automatically requested. Connecting to any other host name will use the usual self-generated certificate. @@ -78,8 +79,8 @@ identity-public-key | string | | | Se identity-url | string | | | Sets the URL of the identity manager. Feature not yet implemented. max-logs-age | string | 72h | 72h, etc. | Sets the maximum age for log entries before they are pruned, in human-readable time format max-logs-size | string | 4G | 400M, 5G, etc. | Sets the maximum size for the log collection, in human-readable memory format -max-prune-txn-batch-size | integer | 1e+06 | 100000, 1e+05, etc. | Sets the maximum number of database transaction records to be pruned during each cleanup pass. -max-prune-txn-passes | integer | 100 | | Sets the maximum number of passes to make during each automatic hourly database transaction record cleanup procedure. +max-prune-txn-batch-size **[RT]** | integer | 1e+06 | 100000, 1e+05, etc. | Sets the maximum number of database transaction records to be pruned during each cleanup pass. +max-prune-txn-passes **[RT]** | integer | 100 | | Sets the maximum number of passes to make during each automatic hourly database transaction record cleanup procedure. max-txn-log-size | string | 10M | 100M, 1G, etc. | Sets the maximum size for the capped txn log collection, in human-readable memory format mongo-memory-profile | string | low | low/default | Sets whether MongoDB uses the least possible memory or the default MongoDB memory profile network | string | | | An OpenStack network UUID. @@ -205,7 +206,6 @@ key value of 'ReadOnlyMethods'. [controllers-creating]: ./controllers-creating.md -[models-config]: ./models-config.md [#excluding-information-audit-log]: #excluding-information-from-the-audit-log [audit-logging]: ./troubleshooting-logs.md#audit-logging [network-spaces]: ./network-spaces.md From 423506e139fc86f90cb32d519b4964d2296c47b6 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 20 Sep 2018 08:19:13 -0400 Subject: [PATCH 048/311] edit charmstore-url key --- src/en/controllers-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index 7b51cd807..9d2d4b5b5 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -71,7 +71,7 @@ bootstrap-timeout | integer | 600 | | Ho bootstrap-retry-delay | integer | 5 | | How long in seconds to wait between connection attempts to a controller bootstrap-address-delay | integer | 10 | | How often in seconds to refresh controller addresses from the API server ca-cert | string | | | The certificate of the CA that signed the controller's CA certificate, in PEM format -charmstore-url | string | | URL | Replaces the internal Charm Store URL of https://api.jujucharms.com/charmstore with a custom one. +charmstore-url | string | https://api.jujucharms.com/charmstore | | Sets the Charm Store URL. controller-uuid | string | | | The key for the UUID of the controller juju-ha-space | string | | | The name of a network space used used for MongoDB replica-set communication in a controller HA context. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). juju-mgmt-space | string | | | The name of a network space used by Juju agents to communicate with controllers. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). From f448f2ba9eed1d1a136742933f225b3e76755830 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 21 Sep 2018 07:40:15 -0400 Subject: [PATCH 049/311] refactor and enhance --- src/en/clouds-lxd-advanced.md | 52 ++++++++++++++++++++-------------- src/en/clouds-lxd-resources.md | 38 +++++++++++++++---------- 2 files changed, 53 insertions(+), 37 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index f3ae35c61..eb828f621 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -1,4 +1,6 @@ Title: Using LXD with Juju - advanced +TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1793661 + bug tracking: https://bugs.launchpad.net/juju/+bug/1793693 # Using LXD with Juju - advanced @@ -22,6 +24,8 @@ unique LXD API endpoint. For the manual method of adding a LXD cloud, see below section [Manually adding a LXD cloud][#clouds-lxd-manual]. + + ```bash juju add-cloud ``` @@ -63,7 +67,10 @@ Then you can bootstrap with 'juju bootstrap lxd-remote' !!! Important: The remote LXD server needs to be available over the network. This is - specified with `lxd init` on the remote host. + specified with `lxd init` on the remote host. When the remote LXD cloud is + custered, the init step does this automatically. + + Now confirm the successful addition of the cloud: @@ -94,13 +101,13 @@ clouds: lxd-remote-manual: type: lxd auth-types: [certificate] - endpoint: 10.55.60.244 + endpoint: https://10.55.60.244:8443 ``` -<--! test if 'interactive' is required in the above --> + -We've call the cloud 'lxd-remote-manual' and the endpoint is the IP address of -the remote LXD host. +We've called the cloud 'lxd-remote-manual' and the endpoint is the IP address +of the remote LXD host. To add cloud 'lxd-remote-manual', assuming the configuration file is `lxd-cloud.yaml` in the current directory, we would run: @@ -111,44 +118,45 @@ juju add-cloud lxd-remote-manual lxd-cloud.yaml ## Adding credentials -As opposed to a local LXD cloud, credentials need to be added prior to creating -a controller for a remote one. +As opposed to a local LXD cloud, in a remote context, credentials need to be +added prior to creating a controller. The [Cloud credentials][credentials] page offers a full treatment of credential management. -Use the interactive `add-credential` command to add your credentials to the new -cloud. The 'certificate' auth type requires you to gather the LXD server -certificate and both the LXD client certificate and key. The client in this -context is Juju. +Use the `add-credential` command to add your credentials to the new cloud: ```bash -juju add-credential lxd-remote +juju add-credential lxd-remote ``` -Example user session: - ```no-highlight -Enter credential name: lxd-remote-creds-cert +Enter credential name: lxd-remote-creds Auth Types certificate interactive -Select auth type [interactive]: certificate +Select auth type [interactive]: -Enter the path to the PEM-encoded LXD server certificate file: server.crt +Enter trust-password: ******* -Enter the path to the PEM-encoded LXD client certificate file: .local/share/juju/lxd/client.crt -Enter the path to the PEM-encoded LXD client key file: .local/share/juju/lxd/client.key -Credential "lxd-remote-creds-cert" added locally for cloud "lxd-remote". +Loaded client cert/key from "/home/ubuntu/.local/share/juju/lxd" +Uploaded certificate to LXD server. + +Credential "lxd-remote-creds" added locally for cloud "lxd-remote". ``` We've called the new credential 'lxd-remote-creds'. When prompted for -'', you should paste your MAAS API key. +'trust-password', you should enter the password that was set up with `lxd init` +on the remote LXD host. !!! Note: - The API key will not be echoed back to the screen. + The trust password will not be echoed back to the screen. + +The 'certificate' authentication type requires you to manually gather the +server certificate and the client certificate & key. + diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index a90d7d80d..00cdce52c 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -43,24 +43,31 @@ Image cache expiration and image synchronization mechanisms are built-in. ## LXD clustering -LXD clustering (v.3 and greater) allows for distributed computing to the extent -that Juju units end up on different cluster nodes (LXD hosts) by default. It -also offers high availability so that the cluster remains functional as long as -more than half of the nodes are up. A downed node will lead to its hosted -containers becoming unavailable. +LXD clustering (lxd `v.3` and greater) allows for distributed computing to the +extent that Juju units end up on different cluster nodes (LXD hosts) by +default. It also offers high availability so that the cluster remains +functional as long as more than half of the nodes are up. A downed node will +lead to its hosted containers becoming unavailable. + +In terms of adding a LXD cloud, Juju is indifferent as to whether it is +clustered or not. Juju connects to a single LXD host and, when prompted for +connection information, you will need to decide which host that is. It should +be noted that if this host becomes unavailable Juju will lose connection to the +entire cluster. -The following caveats apply: +!!! Important: + Each cluster node must have a network bridge that is connected to LXD. This + is to allow the containers to communicate with the controller. - - The controller must reside on a cluster node. This will no longer be the - case starting with v.2.5 of Juju. - - Each cluster node must have a network bridge that is connected to LXD. This - is to allow the containers to communicate with the controller. +Clustering is configured by running `lxd init` on each LXD host (a minimum of +three is recommended). The first host that does so will *initialise* the +cluster and any subsequent node will *join* the cluster. When joining, `sudo` +is required. -Clustering is configured by running `sudo lxd init` on each LXD host (a minimum -of three is recommended). The first host that does so will *initialise* the -cluster and any subsequent node will *join* the cluster. Once the cluster is -set up a controller can be created, as normal, on any of the cluster nodes -(e.g. `juju bootstrap localhost lxd-cluster`). +Once the cluster is set up a controller can be created and will end up randomly +on one of the nodes. See +[Deploying to specific machines][deploying-to-specific-machines] for how to +target specific nodes. !!! Warning: The cluster-creation process will remove any existing containers. In a Juju @@ -204,3 +211,4 @@ assistance with the daemon. See upstream documentation for [logs]: ./troubleshooting-logs.md [credentials]: ./credentials.md [users-creating]: ./users-creating.md +[deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines From f95cc2f8d8be6088a86ac358111c78135cc9557a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 21 Sep 2018 08:46:18 -0400 Subject: [PATCH 050/311] add credentials by file --- src/en/clouds-lxd-advanced.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index eb828f621..8836612ef 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -127,7 +127,7 @@ management. Use the `add-credential` command to add your credentials to the new cloud: ```bash -juju add-credential lxd-remote +juju add-credential lxd-remote ``` ```no-highlight @@ -157,6 +157,18 @@ on the remote LXD host. The 'certificate' authentication type requires you to manually gather the server certificate and the client certificate & key. +```no-highlight +credentials: + lxd-remote: + admin: + auth-type: interactive + trust-password: ubuntu +``` + +```bash +juju add-credential lxd-remote -f lxd-remote-creds.yaml +``` + From 7fa299f8ae396b1dbfe3563a0a5abdcc41a9bc5f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 25 Sep 2018 18:10:02 -0400 Subject: [PATCH 051/311] precision --- src/en/clouds-lxd-advanced.md | 69 ++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 25 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 8836612ef..a00980e4d 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -15,14 +15,15 @@ The topics presented here are: The traditional way of using LXD with Juju is by having both the Juju client and the LXD daemon local to each other. However, since `v.2.5` Juju supports -connecting to a remote LXD daemon. +connecting to a remote LXD daemon. Doing so does not require LXD to be +installed alongside the Juju client. -Use the interactive `add-cloud` command to add your LXD cloud to Juju's list -of clouds. You will need to supply a name you wish to call your cloud and the -unique LXD API endpoint. +Use the `add-cloud` command in interactive mode to add a LXD cloud to Juju's +list of clouds. You will need to supply the name you wish to call your cloud +and the unique LXD API endpoint. For the manual method of adding a LXD cloud, see below section -[Manually adding a LXD cloud][#clouds-lxd-manual]. +[Manually adding a remote LXD cloud][#clouds-lxd-remote-add-manual]. @@ -68,7 +69,7 @@ Then you can bootstrap with 'juju bootstrap lxd-remote' !!! Important: The remote LXD server needs to be available over the network. This is specified with `lxd init` on the remote host. When the remote LXD cloud is - custered, the init step does this automatically. + clustered, the init step does this automatically. @@ -88,9 +89,9 @@ Cloud Regions Default Type Description lxd-remote 1 default lxd LXD Container Hypervisor ``` -### Manually adding a LXD cloud +#### Manually adding a remote LXD cloud -This covers manually adding a LXD cloud to Juju (see +Alternatively, the remote LXD cloud can be added manually to Juju (see [Adding clouds manually][clouds-adding-manually] for background information). The manual method necessitates the use of a [YAML-formatted][yaml] @@ -106,8 +107,8 @@ clouds: -We've called the cloud 'lxd-remote-manual' and the endpoint is the IP address -of the remote LXD host. +We've called the cloud 'lxd-remote-manual'. The endpoint is based on the +`HTTPS` protocoal, port 8443, and the IP address of the remote LXD host. To add cloud 'lxd-remote-manual', assuming the configuration file is `lxd-cloud.yaml` in the current directory, we would run: @@ -116,15 +117,13 @@ To add cloud 'lxd-remote-manual', assuming the configuration file is juju add-cloud lxd-remote-manual lxd-cloud.yaml ``` -## Adding credentials +### Adding credentials As opposed to a local LXD cloud, in a remote context, credentials need to be -added prior to creating a controller. +added prior to creating a controller (see [Cloud credentials][credentials] for +background information). -The [Cloud credentials][credentials] page offers a full treatment of credential -management. - -Use the `add-credential` command to add your credentials to the new cloud: +Use the `add-credential` command to add credentials to the new cloud: ```bash juju add-credential lxd-remote @@ -148,33 +147,53 @@ Credential "lxd-remote-creds" added locally for cloud "lxd-remote". ``` We've called the new credential 'lxd-remote-creds'. When prompted for -'trust-password', you should enter the password that was set up with `lxd init` -on the remote LXD host. +'trust-password', enter the password that was set up with `lxd init` on the +remote LXD host. !!! Note: - The trust password will not be echoed back to the screen. + If the 'certificate' authentication type is chosen in place of + 'interactive' the server and client certificates and the client key will + need to be gathered manually. You will be prompted for the paths to the + three files containing the data. -The 'certificate' authentication type requires you to manually gather the -server certificate and the client certificate & key. +#### Manually adding LXD credentials -```no-highlight +Like adding a cloud manually, a YAML file is needed to manually add +credentials. Here is an example: + +```yaml credentials: - lxd-remote: + lxd-remote-creds: admin: auth-type: interactive trust-password: ubuntu ``` + + +Here, we've named the credential as we did when using the interactive method: +'lxd-remote-creds'. The trust password is set as 'ubuntu'. + +To add credentials for cloud 'lxd-remote', assuming the configuration file is +`lxd-cloud-creds.yaml` in the current directory, we would run: + ```bash -juju add-credential lxd-remote -f lxd-remote-creds.yaml +juju add-credential lxd-remote -f lxd-cloud-creds.yaml ``` +### Next steps + +Now that the cloud and credentials have been added the next step is to create a +controller. See [Creating a controller][clouds-lxd-creating-a-controller] on +the main LXD page. + [yaml]: http://www.yaml.org/spec/1.2/spec.html [clouds-lxd]: ./clouds-LXD -[#clouds-lxd-manual]: #manually-adding-a-lxd-cloud +[#clouds-lxd-remote-add-manual]: #manually-adding-a-remote-lxd-cloud [controllers-creating]: ./controllers-creating.md [clouds-adding-manually]: ./clouds.md#adding-clouds-manually [credentials]: ./credentials.md +[clouds-lxd-creating-a-controller]: ./clouds-LXD.md#creating-a-controller From de7799fbc18a56112a3e13f8f6aeb2b005ec8d1d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 26 Sep 2018 13:26:57 -0400 Subject: [PATCH 052/311] surface command --- src/en/charms-bundles.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/en/charms-bundles.md b/src/en/charms-bundles.md index 188678cd0..e70356cc2 100644 --- a/src/en/charms-bundles.md +++ b/src/en/charms-bundles.md @@ -481,12 +481,18 @@ environments where a Juju controller is unable to contact the Charm Store. ## Saving a bundle and next steps -If you have created your own bundle you will need to save it. In order to do -this you will need to use the Juju GUI. See -[Adding bundles with the GUI][charms-bundles-gui-exporting] for instructions. +If you have created your own bundle you will probably want to save it. This is +done with the `export-bundle` command, which exports a single model +configuration. -!!! Note: - A CLI tool for saving a bundle is currently under development. +For example, to export the currently active model into file `mymodel.yaml`: + +```bash +juju export-bundle --filename mymodel.yaml +``` + +You can also use the Juju GUI to save a bundle. See +[Adding bundles with the GUI][charms-bundles-gui-exporting] for instructions. Once the bundle is saved you can consider these [Next steps][authors-charm-store-next-steps]. From 5d5a011f7d5c7d6f701374fdbdb5417a7ffd28b1 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 27 Sep 2018 09:19:23 -0400 Subject: [PATCH 053/311] add new prompt and variables note --- src/en/help-openstack.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index ff7d4b244..bd67d9091 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -17,10 +17,13 @@ images are set up. This is covered in ## Adding an OpenStack Cloud -Use the interactive `add-cloud` command to add your OpenStack cloud to Juju's +Use the `add-cloud` command to interactively add your OpenStack cloud to Juju's list of clouds. You will need to supply a name you wish to call your cloud and the unique API endpoint, the authentication type(s), and region information. +If you first source your `novarc` file (including the OS_CACERT variable) the +`add-cloud` command will attempt to use some of the variables. + For the manual method of adding an OpenStack cloud, see below section [Manually adding an OpenStack cloud][#clouds-openstack-manual]. @@ -32,31 +35,38 @@ Example user session: ```no-highlight Cloud Types + lxd maas manual + oci openstack + oracle vsphere Select cloud type: openstack -Enter a name for your openstack cloud: mystack +Enter a name for your openstack cloud: myopenstack + +Enter the API endpoint url for the cloud [https://x.x.x.x:5000/v3]: -Enter the API endpoint url for the cloud: https://openstack.example.com:35574/v3.0/ +Enter the filename of the CA certificate to access OpenStack cloud (optional) [/home/ubuntu/cacert.pem]: Auth Types access-key userpass -Select one or more auth types separated by commas: access-key,userpass +Select one or more auth types separated by commas: userpass Enter region name: dev1 -Enter the API endpoint url for the region: https://openstack-dev.example.com:35574/v3.0/ +Enter the API endpoint url for the region [use cloud api url]: Enter another region? (Y/n): n -Cloud "mystack" successfully added -You may bootstrap with 'juju bootstrap mystack' +Successfully read CA Certificate from /home/ubuntu/test_certs/cacert.pem +Cloud "myopenstack" successfully added +You may need to `juju add-credential myopenstack' if your cloud needs additional credentials +Then you can bootstrap with ‘juju bootstrap myopenstack’ ``` Note that it is possible to choose more than one authorisation method - just @@ -75,7 +85,7 @@ Cloud Regions Default Type Description . . . -mystack 1 dev1 openstack +myopenstack 1 dev1 openstack ``` ### Manually adding an OpenStack cloud From 90b5f827427acb41c63a7ca5b7903befc71117de Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 1 Oct 2018 13:35:20 -0400 Subject: [PATCH 054/311] finished testing and text enhancement --- src/en/clouds-lxd-advanced.md | 19 ++++++------------- src/en/credentials.md | 6 ++++++ 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index a00980e4d..c21e9fed4 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -25,8 +25,6 @@ and the unique LXD API endpoint. For the manual method of adding a LXD cloud, see below section [Manually adding a remote LXD cloud][#clouds-lxd-remote-add-manual]. - - ```bash juju add-cloud ``` @@ -49,6 +47,7 @@ Select cloud type: lxd Enter a name for your lxd cloud: lxd-remote Enter the API endpoint url for the remote LXD server: https://10.55.60.244:8443 + Auth Types certificate @@ -67,11 +66,9 @@ Then you can bootstrap with 'juju bootstrap lxd-remote' ``` !!! Important: - The remote LXD server needs to be available over the network. This is - specified with `lxd init` on the remote host. When the remote LXD cloud is - clustered, the init step does this automatically. - - + The remote LXD server needs to be available over the network and is + specified with `lxd init` on the remote host. Networking is enabled + automatically when clustering is chosen. Now confirm the successful addition of the cloud: @@ -105,8 +102,6 @@ clouds: endpoint: https://10.55.60.244:8443 ``` - - We've called the cloud 'lxd-remote-manual'. The endpoint is based on the `HTTPS` protocoal, port 8443, and the IP address of the remote LXD host. @@ -163,14 +158,12 @@ credentials. Here is an example: ```yaml credentials: - lxd-remote-creds: - admin: + lxd-remote: + lxd-remote-creds: auth-type: interactive trust-password: ubuntu ``` - - Here, we've named the credential as we did when using the interactive method: 'lxd-remote-creds'. The trust password is set as 'ubuntu'. diff --git a/src/en/credentials.md b/src/en/credentials.md index 9afb2a411..8df5631df 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -1,6 +1,8 @@ Title: Credentials TODO: Investigate: shouldn't `model-config` have a default-credential setting? Add to mycreds.yaml: cloudsigma, rackspace, and oracle. also openstack using access-key + Investigate: can private keys always be replaced by a file path? + Add remote LXD certs/key (server cert, client cert, client key) table_of_contents: True # Credentials @@ -192,6 +194,10 @@ credentials: auth-type: userpass password: passw0rd user: administrator@xyz.com + lxd-node2: + interactive: + auth-type: interactive + trust-password: ubuntu ``` Credentials are added to Juju on a per-cloud basis. To add credentials for the From 94239748ff3e91ed8fbb12ee063185569ea8ca5b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 1 Oct 2018 17:20:33 -0400 Subject: [PATCH 055/311] refactore and minor improvements --- src/en/clouds-LXD.md | 11 +++++---- src/en/clouds-lxd-advanced.md | 43 ++++++++++++++++++++++++++++++-- src/en/clouds-lxd-resources.md | 45 +--------------------------------- 3 files changed, 48 insertions(+), 51 deletions(-) diff --git a/src/en/clouds-LXD.md b/src/en/clouds-LXD.md index fb3d22de6..b85b2f164 100644 --- a/src/en/clouds-LXD.md +++ b/src/en/clouds-LXD.md @@ -1,6 +1,5 @@ Title: Using LXD with Juju TODO: Warning: Ubuntu release versions hardcoded - 2.5 release will demand significant reword: LXD can be used remotely Warning: Troubleshoot Trusty; bootstrap only works with the lxd snap (and only if it is installed w/o the lxd deb being installed first) table_of_contents: True @@ -171,12 +170,12 @@ Output: +---------------+---------+----------------------+------+------------+-----------+ ``` -## LXD specific features +## Advanced LXD support -Here is a list of noteworthy LXD specific features and differences: +Here is a list of advanced LXD features supported by Juju. - - LXD clustering is supported (`v.2.4.0`). See - [Additional LXD resources][clouds-lxd-resources] for details. + - [LXD clustering][clouds-lxd-advanced-cluster] (`v.2.4.0`) + - [Adding a remote LXD cloud][clouds-lxd-advanced-remote] (`v.2.5.0`) ## Additional LXD resources @@ -205,6 +204,8 @@ See these pages for ideas on what to do next: [models-add]: ./models-adding.md [credentials]: ./credentials.md [clouds-lxd-resources]: ./clouds-lxd-resources.md +[clouds-lxd-advanced-cluster]: ./clouds-lxd-advanced.md#lxd-clustering +[clouds-lxd-advanced-remote]: ./clouds-lxd-advanced.md#adding-a-remote-lxd-cloud [lxd-snap]: ./clouds-lxd-resources.md#using-the-lxd-snap [ubuntu-lxd]: http://www.ubuntu.com/cloud/lxd [charms-constraints-lxd]: ./charms-constraints.md#constraints-and-lxd-containers diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index c21e9fed4..d392e5ecc 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -1,6 +1,4 @@ Title: Using LXD with Juju - advanced -TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1793661 - bug tracking: https://bugs.launchpad.net/juju/+bug/1793693 # Using LXD with Juju - advanced @@ -9,8 +7,49 @@ The main page is [Using LXD with Juju][clouds-lxd]. The topics presented here are: + - LXD clustering - Adding a remote LXD cloud +## LXD clustering + +LXD clustering (lxd `v.3` and greater) allows for distributed computing to the +extent that Juju units end up on different cluster nodes (LXD hosts) by +default. It also offers high availability so that the cluster remains +functional as long as more than half of the nodes are up. A downed node will +lead to its hosted containers becoming unavailable. + +In terms of adding a LXD cloud, Juju is indifferent as to whether it is +clustered or not. Juju connects to a single LXD host and, when prompted for +connection information, you will need to decide which host that is. It should +be noted that if this host becomes unavailable Juju will lose connection to the +entire cluster. + +!!! Important: + Each cluster node must have a network bridge that is connected to LXD. This + is to allow the client to communicate with the Juju machines (containers). + +Clustering is configured by running `lxd init` on each LXD host (a minimum of +three is recommended). The first host that does so will *initialise* the +cluster and any subsequent node will *join* the cluster. When joining, `sudo` +is required. + +Once the cluster is set up a controller can be created and will end up randomly +on one of the nodes. See +[Deploying to specific machines][deploying-to-specific-machines] for how to +target specific nodes. + +In `v.2.5.0` specific cluster nodes can be targeted with the commands +`bootstrap`, `deploy`, and `add-unit`. See +[Deploying to specific machines][deploying-to-specific-machines] for how to do +this. + +!!! Warning: + The cluster-creation process will remove any existing containers. In a Juju + context, this implies that you cannot initialise a cluster *after* having + created a controller. + +See the upstream documentation on [Clustering][lxd-upstream-clustering]. + ## Adding a remote LXD cloud The traditional way of using LXD with Juju is by having both the Juju client diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index 5e6687c62..5f1d583dd 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -1,7 +1,5 @@ Title: Additional LXD resources -TODO: Test certificate access - Move clustering to clouds-lxd-advanced - bug tracking: https://bugs.launchpad.net/juju/+bug/1793291 +TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1793291 table_of_contents: True # Additional LXD resources @@ -12,7 +10,6 @@ up LXD with Juju see [Using LXD with Juju][clouds-lxd]. The topics presented here are: - LXD and images - - LXD clustering - Non-admin user credentials - Useful LXD client commands - Using the LXD snap @@ -42,46 +39,6 @@ subsequent requests will be satisfied by the LXD cache (`/var/lib/lxd/images`). Image cache expiration and image synchronization mechanisms are built-in. -## LXD clustering - -LXD clustering (lxd `v.3` and greater) allows for distributed computing to the -extent that Juju units end up on different cluster nodes (LXD hosts) by -default. It also offers high availability so that the cluster remains -functional as long as more than half of the nodes are up. A downed node will -lead to its hosted containers becoming unavailable. - -In terms of adding a LXD cloud, Juju is indifferent as to whether it is -clustered or not. Juju connects to a single LXD host and, when prompted for -connection information, you will need to decide which host that is. It should -be noted that if this host becomes unavailable Juju will lose connection to the -entire cluster. - -!!! Important: - Each cluster node must have a network bridge that is connected to LXD. This - is to allow the containers to communicate with the controller. - -Clustering is configured by running `lxd init` on each LXD host (a minimum of -three is recommended). The first host that does so will *initialise* the -cluster and any subsequent node will *join* the cluster. When joining, `sudo` -is required. - -Once the cluster is set up a controller can be created and will end up randomly -on one of the nodes. See -[Deploying to specific machines][deploying-to-specific-machines] for how to -target specific nodes. - -In `v.2.5` specific cluster nodes can be targeted with the commands -`bootstrap`, `deploy`, and `add-unit`. See -[Deploying to specific machines][deploying-to-specific-machines] for how to do -this. - -!!! Warning: - The cluster-creation process will remove any existing containers. In a Juju - context, this implies that you cannot initialise a cluster *after* having - created a controller. - -See the upstream documentation on [Clustering][lxd-upstream-clustering]. - ## Non-admin user credentials To grant a regular user access to a LXD-based controller a certificate From a39563b6c3ea95744a472d29d1b50ee403f21428 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 1 Oct 2018 17:40:25 -0400 Subject: [PATCH 056/311] reword necessary --- src/en/clouds-LXD.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/en/clouds-LXD.md b/src/en/clouds-LXD.md index b85b2f164..38bc7b3f1 100644 --- a/src/en/clouds-LXD.md +++ b/src/en/clouds-LXD.md @@ -7,14 +7,13 @@ table_of_contents: True # Using LXD with Juju Choosing [LXD][ubuntu-lxd] as the backing cloud for Juju is an efficient way to -experiment with Juju. It is also very quick to set up. With lightweight -containers acting as Juju machines, even a moderately powerful laptop can -create useful models, or serve as a platform to develop your own charms. Make -sure you have enough local space for the containers though. +work with Juju. Other advantages are that it is quick to set up and does not +require an account with a public cloud vendor. -!!! Note: - Work is currently underway that will allow Juju to connect to remote LXD - hosts. +Traditionally LXD would run local to the Juju client but since `v.2.5.0` Juju +is capable of connecting to remote LXD hosts (see +[Adding a remote LXD cloud][clouds-lxd-advanced-remote]). If you do run it +locally ensure you have enough space for the containers. Constraints can be used with LXD containers (`v.2.4.1`). However, these are not bound to the LXD cloud type (i.e. they can affect containers that are @@ -172,7 +171,7 @@ Output: ## Advanced LXD support -Here is a list of advanced LXD features supported by Juju. +Here is a list of advanced LXD features supported by Juju: - [LXD clustering][clouds-lxd-advanced-cluster] (`v.2.4.0`) - [Adding a remote LXD cloud][clouds-lxd-advanced-remote] (`v.2.5.0`) From 7e6d64690b6c77b7e44fa3798640f32f2512f8ec Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 2 Oct 2018 12:57:02 -0400 Subject: [PATCH 057/311] fix link --- src/en/clouds-lxd-advanced.md | 1 + src/en/clouds-lxd-resources.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index d392e5ecc..49e0df47a 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -229,3 +229,4 @@ the main LXD page. [clouds-adding-manually]: ./clouds.md#adding-clouds-manually [credentials]: ./credentials.md [clouds-lxd-creating-a-controller]: ./clouds-LXD.md#creating-a-controller +[lxd-upstream-clustering]: https://lxd.readthedocs.io/en/latest/clustering/ diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index 5f1d583dd..854fb347c 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -170,7 +170,6 @@ assistance with the daemon. See upstream documentation for [clouds-lxd]: ./clouds-LXD.md [lxd-upstream]: https://lxd.readthedocs.io/en/latest/configuration/ -[lxd-upstream-clustering]: https://lxd.readthedocs.io/en/latest/clustering/ [logs]: ./troubleshooting-logs.md [credentials]: ./credentials.md [users-creating]: ./users-creating.md From 298f8c3c0d3743c5ec7c5e96ed3a69cb62921070 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 3 Oct 2018 11:12:30 -0400 Subject: [PATCH 058/311] fix --- src/en/clouds-lxd-advanced.md | 18 +++++++----------- src/en/clouds-lxd-resources.md | 1 - 2 files changed, 7 insertions(+), 12 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 49e0df47a..656a1a241 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -34,19 +34,14 @@ cluster and any subsequent node will *join* the cluster. When joining, `sudo` is required. Once the cluster is set up a controller can be created and will end up randomly -on one of the nodes. See -[Deploying to specific machines][deploying-to-specific-machines] for how to -target specific nodes. - -In `v.2.5.0` specific cluster nodes can be targeted with the commands -`bootstrap`, `deploy`, and `add-unit`. See -[Deploying to specific machines][deploying-to-specific-machines] for how to do -this. +on one of the nodes. Since `v.2.5.0`, however, specific cluster nodes can be +targeted. See [Deploying to specific machines][deploying-to-specific-machines] +for how to do this. !!! Warning: The cluster-creation process will remove any existing containers. In a Juju - context, this implies that you cannot initialise a cluster *after* having - created a controller. + context, this implies that you must initialise the cluster *before* + creating a controller. See the upstream documentation on [Clustering][lxd-upstream-clustering]. @@ -223,10 +218,11 @@ the main LXD page. [yaml]: http://www.yaml.org/spec/1.2/spec.html -[clouds-lxd]: ./clouds-LXD +[clouds-lxd]: ./clouds-LXD.md [#clouds-lxd-remote-add-manual]: #manually-adding-a-remote-lxd-cloud [controllers-creating]: ./controllers-creating.md [clouds-adding-manually]: ./clouds.md#adding-clouds-manually [credentials]: ./credentials.md [clouds-lxd-creating-a-controller]: ./clouds-LXD.md#creating-a-controller [lxd-upstream-clustering]: https://lxd.readthedocs.io/en/latest/clustering/ +[deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines diff --git a/src/en/clouds-lxd-resources.md b/src/en/clouds-lxd-resources.md index 854fb347c..d3a4972ae 100644 --- a/src/en/clouds-lxd-resources.md +++ b/src/en/clouds-lxd-resources.md @@ -173,4 +173,3 @@ assistance with the daemon. See upstream documentation for [logs]: ./troubleshooting-logs.md [credentials]: ./credentials.md [users-creating]: ./users-creating.md -[deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines From 73b59f095e231212f0d20817eb24355236a8dede Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 3 Oct 2018 18:00:08 -0400 Subject: [PATCH 059/311] improvements --- src/en/clouds-k8s.md | 50 +++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 1b22c5aa1..137234c57 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -1,6 +1,5 @@ Title: Using Kubernetes with Juju -TODO: Once 2.4 is officially released remove support Note and update status output - Should eventually link to k8s-charm developer documentation +TODO: Should eventually link to k8s-charm developer documentation Update when storage becomes a Juju drivable aspect. Add architectural overview/diagram once Juju:k8s becomes stable. Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` @@ -8,15 +7,15 @@ TODO: Once 2.4 is officially released remove support Note and update status out # Using Kubernetes with Juju -Kubernetes (often abbreviated as "k8s") provides a flexible architecture for -managing containerised applications at scale (see the +Kubernetes provides a flexible architecture for managing containerised +applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. -## Juju k8s-specific workflow +!!! Note: + Kubernetes is often abbreviated as "k8s" (pronounced "kate's"). -Here we discuss how building and working with a k8s environment may differ from -a standard Juju workflow. +## Juju k8s-specific workflow The only k8s-specific Juju commands are `add-k8s` and `remove-k8s`. All other concepts and commands are applied in the traditional Juju manner. @@ -46,7 +45,7 @@ backing cloud. To summarise, the steps for using Kubernetes with Juju are: - 1. Obtain a cluster + 1. Obtain a Kubernetes cluster 1. Add the cluster to Juju 1. Create a controller (and optionally a model) 1. Deploy k8s-specific charms @@ -66,10 +65,10 @@ juju deploy kubernetes-core !!! Note: An alternative to using the bundle is to use the `conjure-up` installer. See Ubuntu tutorial - [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up]. + [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] for guidance. Although the tutorial specifically mentions the [Canonical Distribution of Kubernetes][cdk-charm] you can choose the - identical minimal install deployed above from the tool's interface. + identical minimal install deployed above from the installer's interface. Sample output looks like this: @@ -123,12 +122,39 @@ juju scp kubernetes-master/0:config ~/.kube/config We can now take advantage of the `add-k8s` command as it internally parses the copied configuration file from the specified path. This allows us to quickly -add the cluster-cloud, which we have arbitrarily called 'k8cloud': +add the cluster-cloud, which we have arbitrarily called 'k8scloud': ```bash -juju add-k8s k8cloud +juju add-k8s k8scloud ``` +Now confirm the successful addition of the cloud: + +```bash +juju clouds +``` + +Here is a partial output: + +```no-highlight +Cloud Regions Default Type Description +. +. +. +k8scloud 0 kubernetes +``` + +## Add a model + +Add a model in the usual way: + +```bash +juju add-model k8smodel +``` + +This will cause a Kubernetes namespace in the cluster to be created that will +host all of the pods and other resources for that model. + ## Configuration Juju k8s applications support application specific configuration. This allows From c61cd951f17d8b65a55e683a80172fe474ab3943 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sun, 7 Oct 2018 15:56:44 -0400 Subject: [PATCH 060/311] add variables --- src/en/help-openstack.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index bd67d9091..dc9991a4c 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -21,8 +21,16 @@ Use the `add-cloud` command to interactively add your OpenStack cloud to Juju's list of clouds. You will need to supply a name you wish to call your cloud and the unique API endpoint, the authentication type(s), and region information. -If you first source your `novarc` file (including the OS_CACERT variable) the -`add-cloud` command will attempt to use some of the variables. +This command recognises the below variables. Any values found will show up as +default values when the interactive mode is used. For clarity, the +corresponding prompts are given in parentheses: + + - `OS_AUTH_URL` (cloud API endpoint URL) + - `OS_CACERT` (path to the CA certificate file) + - `OS_REGION_NAME` (region) + +These are typically defined in a file called `novarc`. Have your shell source +it (e.g `source novarc`) prior to invoking `add-cloud`. For the manual method of adding an OpenStack cloud, see below section [Manually adding an OpenStack cloud][#clouds-openstack-manual]. From 79b7ea36a70916be8f5767dec79f3c3bbebfbd55 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sun, 7 Oct 2018 15:59:12 -0400 Subject: [PATCH 061/311] trivial --- src/en/help-openstack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index dc9991a4c..b8eb5ef6d 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -30,7 +30,7 @@ corresponding prompts are given in parentheses: - `OS_REGION_NAME` (region) These are typically defined in a file called `novarc`. Have your shell source -it (e.g `source novarc`) prior to invoking `add-cloud`. +it (e.g. `source novarc`) prior to invoking `add-cloud`. For the manual method of adding an OpenStack cloud, see below section [Manually adding an OpenStack cloud][#clouds-openstack-manual]. From 60db4d151e7010c883a04ea879c27bc038500dd0 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 9 Oct 2018 15:04:55 -0400 Subject: [PATCH 062/311] add releaste notes and edit install page --- src/en/reference-install.md | 16 ++++++------- src/en/reference-release-notes.md | 38 +++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 8 deletions(-) diff --git a/src/en/reference-install.md b/src/en/reference-install.md index 6b77fefc1..9368e7b13 100644 --- a/src/en/reference-install.md +++ b/src/en/reference-install.md @@ -7,9 +7,9 @@ distributions, macOS, and Windows. Development releases are also available for testing. Read on for how to install a stable or development version of Juju on your chosen platform. -## Version 2.4.3 +## Version 2.4.4 -The most recent stable version of Juju is 2.4.3. This is the version we +The most recent stable version of Juju is 2.4.4. This is the version we recommend for production use. See the [Release Notes][release-notes-2]. ### Ubuntu @@ -79,7 +79,7 @@ sudo snap install juju --classic For CentOS, you can download Juju from the following archive and install it manually: -[**juju-2.4.3-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) +[**juju-2.4.4-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) ### macOS @@ -100,7 +100,7 @@ brew upgrade juju A Windows installer is available for Juju and can be found here: -[**juju-setup-2.4.3-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) +[**juju-setup-2.4.4-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) ## Development releases @@ -167,9 +167,9 @@ instructions on how to build Juju from source. [snapcraft]: https://snapcraft.io [snapd-install]: https://snapcraft.io/docs/core/install [juju-new-bug]: https://bugs.launchpad.net/juju/+filebug -[juju-win-signed]: https://launchpad.net/juju/2.4.3.4.2/+download/juju-setup-2.4.3-signed.exe -[juju-win-signed-md5]: https://launchpad.net/juju/2.4.3.4.2/+download/juju-setup-2.4.3-signed.exe/+md5 -[juju-centos]: https://launchpad.net/juju/2.4.3.4.2/+download/juju-2.4.3-centos7.tar.gz -[juju-centos-md5]: https://launchpad.net/juju/2.4.3.4.2/+download/juju-2.4.3-centos7.tar.gz/+md5 +[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-setup-2.4.4-signed.exe +[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-setup-2.4.4-signed.exe/+md5 +[juju-centos]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-2.4.4-centos7.tar.gz +[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-2.4.4-centos7.tar.gz/+md5 [juju-launchpad-binaries]: https://launchpad.net/juju/+series [centos-and-other-linuxes]: #centos-and-other-linuxes diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index a939264f3..cb623ca0f 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -5,6 +5,44 @@ Title: Juju Release Notes This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available [here][release-notes-1]. +^# Juju 2.4.4 + + The Juju team is pleased to announce the release of Juju 2.4.4. + + This is a minor update to the 2.4.3 release. In particular, it fixes a + regression of goal-state in the individual related unit status, along with + allowing opening/closing ports without an external network. + + - [LP #1789211](https://bugs.launchpad.net/juju/2.4/+bug/1789211) - opening/closing ports without external network + - [LP #1790647](https://bugs.launchpad.net/juju/2.4/+bug/1790647) - refreshing AWS instance types + - [LP #1713239](https://bugs.launchpad.net/juju/2.4/+bug/1713239) - supporting partition tagging + - [LP #1794739](https://bugs.launchpad.net/juju/2.4/+bug/1794739) - output individual related goal-state in unit status + + For the full list of fixes and additions, see the + [2.4.4 milestone](https://launchpad.net/juju/+milestone/2.4.4). + + ## Get Juju + + The easiest way to install Juju is by using the `snap` package: + + sudo snap install juju --classic + + Those already using the 'stable' snap channel (the default as per the above + command) should be upgraded automatically. Other packages are available for a + variety of platforms (see the [install documentation][reference-install]). + + ## Feedback appreciated + + Let us know how you're using Juju or of any questions you may have. You can + join us on [Discourse][juju-discourse-forum], send us a message on Twitter + (hashtag `#jujucharms`), or talk to us in the `#juju` IRC channel on + freenode. + + ## More information + + To learn more about Juju visit our home page at + [https://jujucharms.com](https://jujucharms.com). + ^# Juju 2.4.3 The Juju team is pleased to announce the release of Juju 2.4.3. From a043a60d1f8ef7d81c7a4364b0a19c850165dc5b Mon Sep 17 00:00:00 2001 From: Nobuto Murata Date: Wed, 10 Oct 2018 11:38:52 +0900 Subject: [PATCH 063/311] Share charms with everyone before promulgating Users may want to share a charm with everyone for testing, then promulgate it as the recommended charm. Fix the stream of the document and clarify that promulgation is not just to publish, but to publish the charm as the recommended one in the charm store. --- src/en/authors-charm-store.md | 44 +++++++++++++++++------------------ src/en/charm-promulgation.md | 2 +- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/en/authors-charm-store.md b/src/en/authors-charm-store.md index cb43a36c9..a3f976135 100644 --- a/src/en/authors-charm-store.md +++ b/src/en/authors-charm-store.md @@ -211,30 +211,10 @@ charm release cs:~kirk/foo-9 --channel edge After running both commands, revision 9 exists in both the stable channel and the edge channel. -## Publishing your charm - -When you have released your charm (or bundle) and you want to make it available -to others you will need to make a *promulgation request*. This is informally -done via the "Charms and Charming" category on the -[Juju Discourse forum][juju-discourse-forum-charms]. - -The '#juju' IRC channel on Freenode and the above Discourse forum remain -excellent resources for questions and comments regarding charm development and -charm promulgation. - -### Promulgation notes - - - The [Charm promulgation][charm-promulgation] page contains information on what - happens once the request is made. - - It is the responsibility of the charm author (and maintainer) to test - their charm to ensure it is of good quality and is secure. - - Promulgation to the top level namespace of the Charm Store does not imply - an endorsement by Canonical. - - Charm authors are encouraged to use their personal or group namespace. - ## Sharing charms and bundles -Sharing is independent of publishing (making public) to the Charm Store. +Sharing is independent of promulgating (making public as the recommended charm) +to the Charm Store. All channels have read and write ACLs. By default, only the owner of the entity exists in these ACLs. @@ -264,6 +244,26 @@ general public. charm grant cs:~kirk/foo everyone ``` +## Promulgate your charm + +When you have released your charm (or bundle) and you want to make it available +to others as the recommended charm you will need to make a *promulgation +request*. This is informally done via the "Charms and Charming" category on the +[Juju Discourse forum][juju-discourse-forum-charms]. + +The '#juju' IRC channel on Freenode and the above Discourse forum remain +excellent resources for questions and comments regarding charm development and +charm promulgation. + +### Promulgation notes + + - The [Charm promulgation][charm-promulgation] page contains information on what + happens once the request is made. + - It is the responsibility of the charm author (and maintainer) to test + their charm to ensure it is of good quality and is secure. + - Promulgation to the top level namespace of the Charm Store does not imply + an endorsement by Canonical. + - Charm authors are encouraged to use their personal or group namespace. diff --git a/src/en/charm-promulgation.md b/src/en/charm-promulgation.md index 14bb2e861..9f0122913 100644 --- a/src/en/charm-promulgation.md +++ b/src/en/charm-promulgation.md @@ -2,7 +2,7 @@ Title: Charm promulgation # Charm promulgation -Charm promulagation is the process of making your charm available on the charm store and visible in searches. This is a manual process and requires a review from a member of the [~charmers][launchpad-group-charmers] Launchpad group. +Charm promulagation is the process of making your charm available on the charm store and visible in searches as the recommended charm. This is a manual process and requires a review from a member of the [~charmers][launchpad-group-charmers] Launchpad group. ## Before you request promulgation From 8351349dc7bf2efae1f88c489bd99cb18ed8d26f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 10 Oct 2018 18:46:35 -0400 Subject: [PATCH 064/311] first pass --- src/en/metadata.yaml | 4 +-- src/en/upgrade-series.md | 74 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 src/en/upgrade-series.md diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 9d3baabea..b9eb2479f 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -154,8 +154,8 @@ navigation: location: howto-prometheus.md - title: Cloud image metadata location: howto-privatecloud.md - - title: Update the series of a controller or machine - location: howto-updateseries.md + - title: Updating a machine series + location: upgrade-series.md - title: Troubleshooting location: troubleshooting.md diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md new file mode 100644 index 000000000..334167ea5 --- /dev/null +++ b/src/en/upgrade-series.md @@ -0,0 +1,74 @@ +Title: Updating a machine series + +# Updating a machine series + +Starting with Juju `v.2.5.0`, to upgrade the series of a machine, be it a +workload or controller machine, the `upgrade-series` command is used. + +Here is an overview of the process: + + 1. The user initiates the upgrade. + 1. Juju removes the machine from the pool of machines, marking it as + unavailable. + 1. A minimum amount of the machine's software is upgraded and some changes + internal to Juju are made. + 1. All units on the machine are taken into account. + 1. At the end of this step, from Juju's standpoint, the machine is now + running the target operating system. + 1. The user manually performs the upgrade of the operating system and makes + any other necessary changes. + 1. The user informs Juju that the machine has been successfully upgraded and + is ready to be reinserted into the machine pool. + +In the examples that follow, the machine in question has an ID of '1' and we'll +be moving from Ubuntu 16.04 LTS (Xenial) to Ubuntu 18.04 LTS (Bionic). + +## Initiating the upgrade + +You initiate the upgrade with the `prepare` sub-command, the machine ID, and +the target series: + +```bash +juju upgrade-series prepare 1 bionic +``` + +You will be asked to confirm the procedure. To avoid this prompt use the +`--agree` option. + +On workload machines, deployed charms will be inspected for a +'pre-series-upgrade' hook. If such a hook exists, it will be run. + +## Upgrading the operating system + +One important step in upgrading the operating system is the upgrade of all +software packages. Apply the standard `do-release-upgrade` command to the +machine via SSH: + +```bash +juju ssh 1 do-release-upgrade +``` + +As a resource, use the [Ubuntu Server Guide][serverguide-upgrade]. Also be sure +to read the [Release Notes][ubuntu-releases] of the target version. + +Make any other required changes now, before moving on to the next step. + +## Informing Juju of a successful upgrade + +You should now verify that the machine has been successfully upgraded. Once +that's done, tell Juju that the machine is ready: + +```bash +juju upgrade-series complete 1 +``` + +On workload machines, deployed charms will be inspected for a +'post-series-upgrade' hook. If such a hook exists, it will be run. + +You're done. The machine is now fully upgraded and is an active Juju machine. + + + + +[serverguide-upgrade]: https://help.ubuntu.com/lts/serverguide/installing-upgrading.html +[ubuntu-releases]: https://wiki.ubuntu.com/Releases From 43c120800492a7c321c2a0281e1c6e9e4e9b5495 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 11 Oct 2018 11:13:14 -0400 Subject: [PATCH 065/311] remove old file; improve new file --- src/en/howto-updateseries.md | 179 ----------------------------------- src/en/upgrade-series.md | 17 ++-- 2 files changed, 11 insertions(+), 185 deletions(-) delete mode 100644 src/en/howto-updateseries.md diff --git a/src/en/howto-updateseries.md b/src/en/howto-updateseries.md deleted file mode 100644 index 27ca6b02c..000000000 --- a/src/en/howto-updateseries.md +++ /dev/null @@ -1,179 +0,0 @@ -Title: Update the series of a controller or machine -TODO: Warning: Juju versions hardcoded - Should eventually remove the two "prior to 2.3" Notes - -# Update the series of a controller or machine - -It may sometimes be necessary to upgrade the operating system version (i.e. -series) of the controller and/or the machines. - -## Upgrading a controller - -### Prerequisites - - 1. Controller admin privileges - 1. An available instance resource in the controller's cloud - -### Recommended method - -At this time there is no way to update the series of a controller. A new -controller will be needed, after which a migration of models from the old -controller to the new one must be performed. - -Create the new controller now. A series can be explicitly set for all -newly-created models (if desired): - -```bash -juju bootstrap --config default-series= -``` - -The controller itself will be deployed using the latest LTS Ubuntu release. Use -option `bootstrap-series` to select something else. - -Now migrate existing models by following the [Migrating models][models-migrate] -page. - -To ensure that all new machines will run the new series set the default series -at the model level. For each migrated model: - -```bash -juju model-config -m default-series= -``` - -Destroy the old controller when done. - -Note that the series running on any existing Juju machines have not yet been -affected (see next section). - -## Upgrading a machine/unit - -For the purpose of this guide, a unit '0' of application 'ghost' which resides -on machine '1' will be used. The series will be updated from 'trusty' to -'xenial'. - -### Prerequisites - - 1. Controller admin privileges - 1. All the charms deployed on the machine must support the new series. - -### Recommended method - -First, for every application, specify the new series: - -```bash -juju set-series ghost xenial -``` - -Then add a new unit of the application to replace each existing unit and remove -the old units: - -```bash -juju add-unit ghost -juju remove-unit ghost/0 -``` - -If you are using a version prior to 2.3 follow the instructions for -[updating an application's series][app-update] before adding and removing -units. - -You are now done. - -### Alternative method - -In some cloud environments, there may not be the resources to update using the -above recommended method. Instead we need to upgrade the existing machine -manually and update the agent data, as shown here: - -!!! Negative "Warning": - This method should be approached with caution. After the series is updated - on an existing machine, the unit agent may not restart cleanly depending on - software dependencies (e.g. software installed with `pip` may need to be - installed in a new location or an application's version was updated - without intent). - -#### Update series for new units - -!!! Note: - If you are using a version of Juju prior to 2.3 follow the instructions for - [updating an application's series][app-update]. - -Let Juju know what series should be used for any new units of the application: - -```bash -juju set-series ghost xenial -``` - -#### Upgrade the existing machine - -!!! Note: - If you are using a version prior to 2.3 follow the instructions for - [updating an machine's series][mach-update]. - -Start by logging in to the machine: - -```bash -juju ssh ghost/0 -``` - -Then follow the [Ubuntu Server Guide][serverguide-upgrade] on upgrading an -Ubuntu release. Be sure to read the [Release Notes][ubuntu-releases] of the -target version. - -If asked during the upgrade, it's recommended to keep currently-installed -versions of configuration files. - -#### Update agent data on the upgraded machine - -!!! Negative "Warning": - If the Python version has changed between the two series **and** the charm - uses `pip` to install packages then it will be necessary to force the unit - to install the new Python packages by running the following command on the - unit's machine prior to restarting the unit's service: - `sudo rm /var/lib/juju/agents/unit*/charm/wheelhouse/.bootstrapped` . - -Update the agent data on the newly updated machine/unit appropriate for the new -series and restart the agents: - -```bash -juju ssh ghost/0 -- sudo juju-updateseries --from-series trusty --to-series xenial --start-agents -``` - -#### Verify the agents are running - -On every machine, there is a machine service agent and, for each running unit, -a unit service agent. To check that they restarted properly after the upgrade: - -```bash -sudo systemctl status jujud* -``` - -Sample output: - -```no-highlight -● jujud-unit-ghost-0.service - juju unit agent for ghost/0 - Loaded: loaded (/var/lib/juju/init/jujud-unit-ghost-0/jujud-unit-ghost-0.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2017-10-04 22:07:13 UTC; 2min 39s ago - -● jujud-machine-1.service - juju agent for machine-1 - Loaded: loaded (/var/lib/juju/init/jujud-machine-1/jujud-machine-1.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2017-10-04 22:07:13 UTC; 2min 39s ago -``` - -#### Let Juju know of the upgraded machines and agents - -Once all machines and agents have been updated we need to inform Juju of this -fact. Here we refer to our example machine with an ID of '1': - -```bash -juju set-series 1 xenial -``` - - - - -[models-migrate]: ./models-migrate.html -[app-update]: https://jujucharms.com/docs/2.2/howto-applicationupdateseries -[mach-update]: https://jujucharms.com/docs/2.2/howto-machineupdateseries -[serverguide-upgrade]: https://help.ubuntu.com/lts/serverguide/installing-upgrading.html -[ubuntu-releases]: https://wiki.ubuntu.com/Releases -[systemd]: https://wiki.ubuntu.com/SystemdForUpstartUsers diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 334167ea5..0e11e31da 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -8,21 +8,26 @@ workload or controller machine, the `upgrade-series` command is used. Here is an overview of the process: 1. The user initiates the upgrade. - 1. Juju removes the machine from the pool of machines, marking it as - unavailable. + 1. The machine is removed from the pool of available machines in the sense + that charms can not be deployed upon it. 1. A minimum amount of the machine's software is upgraded and some changes internal to Juju are made. 1. All units on the machine are taken into account. 1. At the end of this step, from Juju's standpoint, the machine is now running the target operating system. 1. The user manually performs the upgrade of the operating system and makes - any other necessary changes. - 1. The user informs Juju that the machine has been successfully upgraded and - is ready to be reinserted into the machine pool. + any other necessary changes. This should be accompanied by a maintenance + window managed by the user. + 1. The user informs Juju that the machine has been successfully upgraded. The + machine is reinserted into the machine pool. + +!!! Important: + At no time does Juju take any action to prevent the machine from servicing + workload client requests. In the examples that follow, the machine in question has an ID of '1' and we'll be moving from Ubuntu 16.04 LTS (Xenial) to Ubuntu 18.04 LTS (Bionic). - + ## Initiating the upgrade You initiate the upgrade with the `prepare` sub-command, the machine ID, and From 9497c3bd98ada3364696a9c3edfad91b8008fc83 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 11 Oct 2018 11:35:27 -0400 Subject: [PATCH 066/311] trivial --- src/en/upgrade-series.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 0e11e31da..47edd205f 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -58,7 +58,7 @@ to read the [Release Notes][ubuntu-releases] of the target version. Make any other required changes now, before moving on to the next step. -## Informing Juju of a successful upgrade +## Completing the upgrade You should now verify that the machine has been successfully upgraded. Once that's done, tell Juju that the machine is ready: From 2fb916a4770b9a71cc3552e43aa9373cb3088ec9 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 11 Oct 2018 14:39:03 -0400 Subject: [PATCH 067/311] put back controller upgrade steps --- src/en/models-migrate.md | 1 + src/en/upgrade-series.md | 66 ++++++++++++++++++++++++++++++++-------- 2 files changed, 55 insertions(+), 12 deletions(-) diff --git a/src/en/models-migrate.md b/src/en/models-migrate.md index dc33b8826..4ab44580b 100644 --- a/src/en/models-migrate.md +++ b/src/en/models-migrate.md @@ -2,6 +2,7 @@ Title: Migrating models TODO: Needs adding to navigation How are subnet and end point bindings handled? Check and add migration resources for different controllers + Critical: review and testing required # Migrating models diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 47edd205f..fd8f77930 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -1,9 +1,17 @@ Title: Updating a machine series +TODO: warning: ubuntu code names hardcoded # Updating a machine series -Starting with Juju `v.2.5.0`, to upgrade the series of a machine, be it a -workload or controller machine, the `upgrade-series` command is used. +Starting with Juju `v.2.5.0`, to upgrade the series of a machine, the +`upgrade-series` command is used. + +!!! Important: + The `upgrade-series` command does not support upgrading a controller. See + below section [Upgrading a controller machine][#upgrading-a-controller] for + how to do that using an alternate method. + +## Upgrading a workload machine Here is an overview of the process: @@ -21,14 +29,13 @@ Here is an overview of the process: 1. The user informs Juju that the machine has been successfully upgraded. The machine is reinserted into the machine pool. -!!! Important: - At no time does Juju take any action to prevent the machine from servicing - workload client requests. +At no time does Juju take any action to prevent the machine from servicing +workload client requests. In the examples that follow, the machine in question has an ID of '1' and we'll be moving from Ubuntu 16.04 LTS (Xenial) to Ubuntu 18.04 LTS (Bionic). -## Initiating the upgrade +### Initiating the upgrade You initiate the upgrade with the `prepare` sub-command, the machine ID, and the target series: @@ -40,10 +47,10 @@ juju upgrade-series prepare 1 bionic You will be asked to confirm the procedure. To avoid this prompt use the `--agree` option. -On workload machines, deployed charms will be inspected for a -'pre-series-upgrade' hook. If such a hook exists, it will be run. +The deployed charms will be inspected for a 'pre-series-upgrade' hook. If such +a hook exists, it will be run. -## Upgrading the operating system +### Upgrading the operating system One important step in upgrading the operating system is the upgrade of all software packages. Apply the standard `do-release-upgrade` command to the @@ -58,7 +65,7 @@ to read the [Release Notes][ubuntu-releases] of the target version. Make any other required changes now, before moving on to the next step. -## Completing the upgrade +### Completing the upgrade You should now verify that the machine has been successfully upgraded. Once that's done, tell Juju that the machine is ready: @@ -67,13 +74,48 @@ that's done, tell Juju that the machine is ready: juju upgrade-series complete 1 ``` -On workload machines, deployed charms will be inspected for a -'post-series-upgrade' hook. If such a hook exists, it will be run. +Deployed charms will be inspected for a 'post-series-upgrade' hook. If such a +hook exists, it will be run. You're done. The machine is now fully upgraded and is an active Juju machine. +## Upgrading a controller machine + +At this time Juju does not support the series upgrade of a controller. A new +controller will be needed, after which a migration of models from the old +controller to the new one must be performed. + +Create the new controller now. Here, we're using AWS and have called the new +controller 'aws-new': + +```bash +juju bootstrap aws aws-new +``` + +The controller itself will be deployed using Ubuntu 18.04 LTS (Bionic). Use +option `bootstrap-series` to select something else. + +Now migrate existing models by following the [Migrating models][models-migrate] +page. + +To ensure that all new machines will run the new series (like the controller, +we'll use 'bionic') set the default series at the model level. For each +migrated model: + +```bash +juju model-config -m default-series=bionic +``` + +Destroy the old controller when done: + +```bash +juju destroy-controller aws-old +``` + [serverguide-upgrade]: https://help.ubuntu.com/lts/serverguide/installing-upgrading.html [ubuntu-releases]: https://wiki.ubuntu.com/Releases +[models-migrate]: ./models-migrate.md +[#upgrading-a-controller]: #upgrading-a-controller-machine From 7a2d782814ec9094ba4936801e60bef0353afe98 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 11 Oct 2018 19:26:30 -0400 Subject: [PATCH 068/311] add main points and begin filling in --- src/en/whats-new.md | 110 ++++++++++++++++++++++---------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/src/en/whats-new.md b/src/en/whats-new.md index f8182a089..5d52ffcf4 100644 --- a/src/en/whats-new.md +++ b/src/en/whats-new.md @@ -1,84 +1,84 @@ -Title: What's new in 2.4 +Title: What's new in 2.5 -# What's new in 2.4 +# What's new in 2.5 -The latest release of Juju has focused a little more on under-the-hood -improvements, making Juju much more efficient at scale, but there are -some major changes you should know about, which we have summarised here. +??????? - -For full details on this release, see the [2.4 release notes][release-notes]. +For full details on this release, see the [2.5 release notes][release-notes]. If you are new to Juju, you will probably want to read the [Getting started][getting-started] guide first. +## Kubernetes support +See [][]. -## 18.04 LTS (Bionic) support +## Remote LXD support -Juju now fully supports running both containers and workloads on the latest -LTS release of Ubuntu! Currently, the default is to use 16.04 LTS (Xenial), -but you can choose a different series when bootstrapping or deploying. For -example, to create a new controller: +A remote LXD cloud is now possible. Like other custom clouds, it is added via +the enhanced `add-cloud` command. The Juju client can then request a controller +be created on the remote LXD host. This naturally augments the already +supported LXD clustering feature; both features are expected to be used in +tandem. -```bash -juju bootstrap --bootstrap-series=bionic localhost localcloud -``` +See [][]. -Workloads will automatically be deployed on the newest available series -supported by the charm. +## Oracle Cloud Infrastructure (OCI) support + +OCI is the new cloud framework from Oracle. +See [][]. -## Controller network spaces +## Rework of machine series upgrades -Two new controller configuration settings have been introduced to make it -easier to specify which network spaces and/or subnets should be used for -communication with the controller by workload agents, or between -controllers in the case of a Highly Available setup: +Juju workload machines can now have their series updated natively. In previous +versions the recommended approach was to add a new unit and remove the old one. +With `v.2.5` a new command makes its appearance: `upgrade-series`. By design, +the bulk of the underlying operating system is upgraded manually by the user by +way of standard tooling (e.g. `do-release-upgrade`). Note that the upgrade of +machines hosting controllers is not supported and the documented method of +creating a new controller and migrating models is still the recommended +procedure. - * juju-mgmt-space - * juju-ha-space +See [][]. -For more information on how to use these new options, please read the -documentation on [configuring controllers][controllers-config]. +## CLI bundle export support -## Model Ownership +A model's configuration can now be saved as a bundle at the command line using +the new `export-bundle` command. Previously, the Juju GUI was needed to do +this. -In previous releases, the user who originally created a new model had special -privileges over it. With this release, multiple users can be given admin -status, and any user can have admin status taken away, so there is -nothing unique about the original creator. +See [][]. -## Cloud credential changes +## New tool for comparing a bundle and model -Credentials are essential for the Juju controller to authenticate and perform -actions on the underlying cloud. Juju has always kept credentials remotely on -the controller in addition to credentials stored locally by the Juju client. -This isn't going to change, but the ambiguity of where particular credentials -are stored has caused some confusion, so a new command has been added. + +A model and a bundle can now be compared using the new `diff-bundle` command. +This will help in complex enterprise setups where changes have been made to a +model yet a new bundle deployment of the initial model is desired. -To discover the credentials for the current user and cloud, run: +See [][]. -```bash -juju show-credentials -``` +## Enhancements for adding OpenStack clouds -Additionally, the `show-model` command now outputs some additional information -on credentials, for example: +The adding of an OpenStack cloud, via `add-cloud`, now supports the inclusion +of a CA certificate in cases where it is necessary. This command also now +recognises certain environment variables used by OpenStack - typically via its +`novarc` file. The corresponding values will be used as default values when +`add-cloud` is used in interactive mode. + +See [][]. + +## LXD availability zones + +See [][]. + +## Charm Store controller configuration key added + +See [][]. -```bash - credential: - name: default - owner: admin - cloud: aws -``` -will appear in the YAML output. - [getting-started]: ./getting-started.md -[release-notes]: ./reference-release-notes.md#juju_2.4.0 -[controllers-config]: ./controllers-config.md -[credential-command]: ./commands.md#show-credentials - +[release-notes]: ./reference-release-notes.md#juju_2.5.0 From fbf74777124e2b5b995c9ab1f3e22139ac6b455a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 12 Oct 2018 12:57:10 -0400 Subject: [PATCH 069/311] add prompt; add compatible charms --- src/en/upgrade-series.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index fd8f77930..f0c12d659 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -44,8 +44,11 @@ the target series: juju upgrade-series prepare 1 bionic ``` -You will be asked to confirm the procedure. To avoid this prompt use the -`--agree` option. +You will be asked to confirm the procedure. Use the `--agree` option to avoid +this prompt. + +All charms associated with the machine must support the target series in order +for the command to complete successfully. An error will be emitted otherwise. The deployed charms will be inspected for a 'pre-series-upgrade' hook. If such a hook exists, it will be run. From 2c2f9d9ce9785fb9a9a79971cd3d67d4c5ec2a02 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 07:17:54 -0400 Subject: [PATCH 070/311] addition --- src/en/whats-new.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/src/en/whats-new.md b/src/en/whats-new.md index 5d52ffcf4..cefef17e1 100644 --- a/src/en/whats-new.md +++ b/src/en/whats-new.md @@ -13,19 +13,27 @@ If you are new to Juju, you will probably want to read the See [][]. -## Remote LXD support +## Remote LXD support and LXD clustering A remote LXD cloud is now possible. Like other custom clouds, it is added via the enhanced `add-cloud` command. The Juju client can then request a controller -be created on the remote LXD host. This naturally augments the already +be created on the remote LXD host. This naturally bolsters the already supported LXD clustering feature; both features are expected to be used in tandem. +Placement directives are supported for LXD clustering. You can specify upon +which LXD host (cluster node) a Juju machine will be created. These nodes +effectively become availability zones for a LXD clustered cloud. + See [][]. ## Oracle Cloud Infrastructure (OCI) support -OCI is the new cloud framework from Oracle. + +OCI is the new cloud framework from Oracle and Juju now supports it out of the +box. Juju's cloud name for this cloud is 'oci'. At this time both OCI and +Oracle Classic are supported but it is expected that Classic will eventually +be obsoleted. See [][]. @@ -45,14 +53,14 @@ See [][]. ## CLI bundle export support A model's configuration can now be saved as a bundle at the command line using -the new `export-bundle` command. Previously, the Juju GUI was needed to do -this. +the new `export-bundle` command. Previously, the Juju GUI was needed to save +a bundle. See [][]. ## New tool for comparing a bundle and model - + A model and a bundle can now be compared using the new `diff-bundle` command. This will help in complex enterprise setups where changes have been made to a model yet a new bundle deployment of the initial model is desired. @@ -69,11 +77,19 @@ recognises certain environment variables used by OpenStack - typically via its See [][]. -## LXD availability zones +## Charm Store controller configuration key added + +A custom Charm Store can be configured by specifying a URL during the creation +of a controller (`bootstrap`). See [][]. -## Charm Store controller configuration key added +## Charm support for LXD profiles + + +??????? +`status --format yaml` +`show-machines` See [][]. From 1a95f964cfd505be8897556551c908784c41f9cb Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 07:54:07 -0400 Subject: [PATCH 071/311] remove extraneous characters; enhance TODO --- src/en/clouds-oci.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index ff7fb200a..f239704f3 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -1,12 +1,12 @@ Title: Using Oracle Cloud Infrastructure with Juju -TODO: Review required: 2.5 changes still to come +TODO: Review required: 2.5 changes still to come (baked-in, then test trial accounts) # Using Oracle Cloud Infrastructure with Juju -Juju has built-in support (!!!!) for [Oracle Cloud Infrastructure][oracle-oci] -(OCI), Oracle's public cloud. This means that there is no need to add the -Oracle cloud to Juju. An exception to this is if you are using a trial account. -Both types of accounts, paid and trial, are covered here. +Juju has built-in support for [Oracle Cloud Infrastructure][oracle-oci] (OCI), +Oracle's public cloud. This means that there is no need to add the OCI cloud +to Juju. An exception to this is if you are using a trial account. Both types +of accounts, paid and trial, are covered here. This page will cover the following steps: @@ -121,7 +121,7 @@ below (hint: the endpoint domain should be resolvable using DNS). Use the interactive `add-cloud` command to add your OCI cloud to Juju's list of clouds. You will need to supply a name you wish to call your cloud and -!!!!!! +your region. For the manual method of adding an OCI cloud, see below section [Manually adding an OCI cloud][#clouds-oci-manual]. @@ -139,7 +139,7 @@ Cloud Types manual oci openstack - oracle !!!!!!!!!!!! + oracle vsphere Select cloud type: oci @@ -150,7 +150,7 @@ Enter region name: us-ashburn-1 Enter another region? (y/N): N -Cloud "oci-cloud" successfully added +Cloud "oci-test" successfully added You may need to `juju add-credential oci-test' if your cloud needs additional credentials then you can bootstrap with 'juju bootstrap oci-test' From 40331291ca0f92802303c7263365550270390db8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 08:31:18 -0400 Subject: [PATCH 072/311] improvements --- src/en/help-openstack.md | 4 +-- src/en/howto-privatecloud.md | 2 ++ src/en/metadata.yaml | 65 +++++++++++------------------------- 3 files changed, 24 insertions(+), 47 deletions(-) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index 1cb082263..6eb0d406e 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -135,7 +135,7 @@ The above steps are all you need to use most OpenStack clouds which are configured for general use. If this is your own cloud, you will also need to additionally provide stream information so that the cloud can fetch the relevant images for Juju to use. This is covered in the section on -[private clouds][simplestreams]. +[Private cloud metadata][private-cloud-metadata]. ## Creating a controller @@ -184,7 +184,7 @@ See these pages for ideas on what to do next: [yaml]: http://www.yaml.org/spec/1.2/spec.html -[simplestreams]: ./howto-privatecloud.html +[private-cloud-metadata]: ./howto-privatecloud.html [credentials]: ./credentials.html [manual-openstack]: ./clouds-openstack-manual.html [controllers-creating]: ./controllers-creating.md diff --git a/src/en/howto-privatecloud.md b/src/en/howto-privatecloud.md index 681fd86a3..ac4492e87 100644 --- a/src/en/howto-privatecloud.md +++ b/src/en/howto-privatecloud.md @@ -1,4 +1,6 @@ Title: Setting up image metadata for private clouds with Simplestreams +TODO: Critical: review required + Change title to: "Private cloud metadata" # Set up image metadata for a Private OpenStack Cloud using Simplestreams diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 7c880cbda..5968138b0 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -3,49 +3,34 @@ navigation: - title: About Juju location: about-juju.md - - title: Take a tour + - title: Try it out location: getting-started.md - title: Install Juju location: reference-install.md - - title: Release notes - location: reference-release-notes.md + - title: What's new in 2.5 + location: whats-new.md + + - title: Concepts + location: juju-concepts.md + + - title: Tutorials + + children: + - title: Local Juju with LXD cloud + location: tut-lxd.md + - title: Controllers and Models + location: tut-google.md + - title: Sharing and Users + location: tut-users.md - title: User Guide children: - - title: Concepts - location: juju-concepts.md - title: Clouds location: clouds.md - children: - - title: Amazon AWS - location: help-aws.md - - title: Microsoft Azure - location: help-azure.md - - title: Google GCE - location: help-google.md - - title: Joyent - location: help-joyent.md - - title: LXD - location: clouds-LXD.md - - title: MAAS - location: clouds-maas.md - - title: Manual - location: clouds-manual.md - - title: OpenStack - location: help-openstack.md - - title: Private cloud metadata - location: howto-privatecloud.md - - title: Oracle Compute - location: help-oracle.md - - title: Rackspace - location: help-rackspace.md - - title: VMware vSphere - location: help-vmware.md - - title: Using Juju location: charms.md @@ -93,6 +78,8 @@ navigation: location: actions.md - title: Working with resources location: charms-resources.md + - title: Private cloud metadata + location: howto-privatecloud.md - title: Tools - title: Networking @@ -108,16 +95,6 @@ navigation: - title: Troubleshooting location: troubleshooting.md - - title: Tutorials - - children: - - title: Local Juju with LXD cloud - location: tut-lxd.md - - title: Controllers and Models - location: tut-google.md - - title: Sharing and Users - location: tut-users.md - - title: Miscellaneous children: @@ -147,16 +124,14 @@ navigation: location: credentials.md - title: Juju client location: client.md - - title: What's new in 2.4 - location: whats-new.md - title: Developer Guide - title: Reference children: - - title: Introducing Juju 2 - location: introducing-2.md + - title: Release notes + location: reference-release-notes.md - title: Juju commands location: commands.md - title: Juju constraints From 5c0049931e47b17e85b43f3e799e09437a56c10d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 12:48:53 -0400 Subject: [PATCH 073/311] remove some files; improvements --- src/en/client.md | 4 ++-- src/en/juju-concepts.md | 22 +++++++++++++--------- src/en/metadata.yaml | 8 -------- src/en/tools-amulet.md | 19 ------------------- src/en/tools-charm-helpers.md | 18 ------------------ 5 files changed, 15 insertions(+), 56 deletions(-) delete mode 100644 src/en/tools-amulet.md delete mode 100644 src/en/tools-charm-helpers.md diff --git a/src/en/client.md b/src/en/client.md index 4b1cf39c6..a3eae6a7d 100644 --- a/src/en/client.md +++ b/src/en/client.md @@ -1,6 +1,6 @@ -Title: Juju client +Title: Client -# Juju client +# Client This page covers various operations that can be applied to the Juju client, the software that is used to manage Juju, whether as an administrator or as a diff --git a/src/en/juju-concepts.md b/src/en/juju-concepts.md index 0fbf1e622..aa4cfd18a 100644 --- a/src/en/juju-concepts.md +++ b/src/en/juju-concepts.md @@ -1,5 +1,6 @@ Title: Concepts and terms TODO: developer-layers-interfaces.md also includes definitions + Update LXD image to reflect remote LXD clouds # Concepts and terms @@ -39,7 +40,7 @@ and are used to run workloads. ![machine][img__models] -See [Juju models][models] for more information. +See [Models][models] for more information. ## Charm @@ -56,7 +57,7 @@ installed within it: ![machine][img__charms] -To learn more about charms see [Introduction to Juju Charms][charms]. +To see what you can do charms read the [Charms][charms] page! ## Bundle @@ -204,6 +205,8 @@ system as the Juju client: Although LXD itself can operate over the network, Juju does not support this. The client *must* be local to the LXD containers. +See the [Client][client] page for how to backup and upgrade the Juju client. + ## Agent A Juju *agent* is software that runs on every Juju machine. There is a *machine @@ -237,15 +240,16 @@ tweaked if desired. See [maas]: https://maas.io "Metal as a Service" [lxd]: https://linuxcontainers.org/lxd/ [charm-store]: https://jujucharms.com/store -[charms]: ./charms.html +[charms]: ./charms.md [charms-bundles]: ./charms-bundles.md -[charms-relations]: ./charms-relations.html -[clouds]: ./clouds.html -[controllers]: ./controllers.html -[models]: ./models.html +[charms-relations]: ./charms-relations.md +[clouds]: ./clouds.md +[controllers]: ./controllers.md +[models]: ./models.md +[client]: ./client.md [charm-store-wordpress]: https://jujucharms.com/wordpress/ -[agent-versions-and-streams]: ./models-config.html#agent-versions-and-streams -[troubleshooting-logs#juju-agents]: ./troubleshooting-logs.html#juju-agents +[agent-versions-and-streams]: ./models-config.md#agent-versions-and-streams +[troubleshooting-logs#juju-agents]: ./troubleshooting-logs.md#juju-agents [img__relations]: ./media/juju-relations.png [img__units]: ./media/juju-machine-units.png diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index f5d1a700c..7cf7310c9 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -97,14 +97,6 @@ navigation: location: charms-metrics.md - title: Exposing applications location: charms-exposing.md - - title: Controllers - location: controllers.md - - title: Models - location: models.md - - title: Juju client - location: client.md - - title: About Juju - location: about-juju.md - title: Reference diff --git a/src/en/tools-amulet.md b/src/en/tools-amulet.md deleted file mode 100644 index d43b8152b..000000000 --- a/src/en/tools-amulet.md +++ /dev/null @@ -1,19 +0,0 @@ -Title: Amulet - -# Amulet, a Juju test library - -Amulet is a Python library for deploying, manipulating, and testing Juju -workloads (collections of related applications). - -With Amulet you can: - -* Deploy, relate, configure, and scale applications imperatively -* Deploy a preconfigured workload using a bundle file -* Execute application actions and inspect the results -* Run arbitrary commands against deployed units and inspect the results. - -## Getting Started - -For instructions on installing and using Amulet, along with -examples and complete API documentation, please refer to the official -[package documentation](http://pythonhosted.org/amulet/). diff --git a/src/en/tools-charm-helpers.md b/src/en/tools-charm-helpers.md deleted file mode 100644 index aab731376..000000000 --- a/src/en/tools-charm-helpers.md +++ /dev/null @@ -1,18 +0,0 @@ -Title: Charm helpers - -# Charm Helpers - -Charm Helpers is a Python library that simplifies charm development by -providing a rich collection of helpful utilities for: - -* Interacting with the host machine and environment -* Responding to hook events -* Reading and writing charm configuration -* Installing dependencies -* Much, much more! - -## Getting Started - -For instructions on installing and using Charm Helpers, along with -examples and complete API documentation, please refer to the official -[package documentation](https://charm-helpers.readthedocs.io/). From 414c0cc8342fde17e52d0fc8e84e3cc8786b4518 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 13:44:06 -0400 Subject: [PATCH 074/311] add links; minor --- src/en/metadata.yaml | 12 ++++++++++-- src/en/troubleshooting.md | 4 ++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 7cf7310c9..8cc871858 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -47,8 +47,6 @@ navigation: location: controllers-ha.md - title: Application high availability location: charms-ha.md - - title: Troubleshooting - location: troubleshooting.md - title: Advanced topics @@ -76,6 +74,14 @@ navigation: - title: Network spaces location: network-spaces.md + - title: Troubleshooting + + children: + - title: Troubleshooting guidelines + location: troubleshooting.md + - title: Juju logs + location: troubleshooting-logs.md + - title: Miscellaneous children: @@ -115,6 +121,8 @@ navigation: location: reference-hook-tools.md - title: metadata.yaml location: authors-charm-metadata.md + - title: Charm writing + location: https://docs.jujucharms.com/2.4/en/developer-getting-started - title: API docs location: http://godoc.org/github.com/juju/juju/api - title: Status values diff --git a/src/en/troubleshooting.md b/src/en/troubleshooting.md index 11dba650b..3a9a84782 100644 --- a/src/en/troubleshooting.md +++ b/src/en/troubleshooting.md @@ -1,8 +1,8 @@ -Title: Troubleshooting +Title: Troubleshooting guidelines TODO: Logs from the machines/applications Review required (factoid: there are 12 instances of the word 'details') -# Troubleshooting +# Troubleshooting guidelines Juju does a brilliant job at simplifying the deployment of big software at scale. But trying to accommodate every variation of model, cloud and connection From d52ce892da7f1b106e111985f2f7c0efaae2c7d3 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 14:07:03 -0400 Subject: [PATCH 075/311] tweak menu; remove file --- src/en/charms-config.md | 4 ++-- src/en/charms-deploying.md | 2 +- src/en/charms-destroy.md | 4 ++-- src/en/charms-fan.md | 4 ++-- src/en/controllers-gui.md | 5 +---- src/en/metadata.yaml | 10 ++++------ src/en/network-spaces.md | 4 ++-- src/en/reference-numbering.md | 27 --------------------------- 8 files changed, 14 insertions(+), 46 deletions(-) delete mode 100644 src/en/reference-numbering.md diff --git a/src/en/charms-config.md b/src/en/charms-config.md index 8f0ecc54e..2723223a0 100644 --- a/src/en/charms-config.md +++ b/src/en/charms-config.md @@ -1,6 +1,6 @@ -Title: Application configuration +Title: Configuring applications -# Application Configuration +# Configuring applications When deploying an application, the charm you use will often support or even require specific configuration options to be set. diff --git a/src/en/charms-deploying.md b/src/en/charms-deploying.md index c81179094..b0aa8b836 100644 --- a/src/en/charms-deploying.md +++ b/src/en/charms-deploying.md @@ -102,7 +102,7 @@ It is possible to deploy applications using local charms. See Deployed applications usually start with a sane default configuration. However, for some applications it may be desirable (and quicker) to configure them at deployment time. This can be done whether a charm is deployed from the Charm -Store or from a local charm. See [Application configuration][charms-config] for +Store or from a local charm. See [Configuring applications][charms-config] for more on this. ## Deploying to LXD containers diff --git a/src/en/charms-destroy.md b/src/en/charms-destroy.md index 4dcb930c5..03ab6d62a 100644 --- a/src/en/charms-destroy.md +++ b/src/en/charms-destroy.md @@ -1,8 +1,8 @@ -Title: Removing Juju objects +Title: Removing things TODO: remove-application|unit should mention in what circumstances the associated machine is removed (other units or containers will prevent this) remove-machine should mention in what circumstances the machine is not removed (other units or containers will prevent this) -# Removing Juju objects +# Removing things This section looks at how to remove the various objects you will encounter as you work with Juju. These are: diff --git a/src/en/charms-fan.md b/src/en/charms-fan.md index 4b9792512..8bc7ad7a2 100644 --- a/src/en/charms-fan.md +++ b/src/en/charms-fan.md @@ -1,9 +1,9 @@ -Title: Juju and Fan networking +Title: Fan container networking TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1733354 (remove constraints Note if no longer required) hardcoded: default AWS instance type of 'm3.medium' consider a third example: manually configure the Fan with Azure -# Juju and Fan networking +# Fan container networking Fan networking addresses a need raised by the proliferation of container usage in an IPv4 context: the ability to manage the address space such that network diff --git a/src/en/controllers-gui.md b/src/en/controllers-gui.md index 105760d91..22b75e3c5 100644 --- a/src/en/controllers-gui.md +++ b/src/en/controllers-gui.md @@ -15,7 +15,7 @@ comprise them, and the machines available. Additionally, the GUI can talk with the charm store in order to search, browse, and deploy charms to your environment. -# Using the GUI +## Using the GUI Juju GUI is now automatically included in every Juju controller after bootstrapping, thus eliminating the need to additionally deploy the Juju GUI @@ -191,6 +191,3 @@ monitoring type scenario. read-only mode in the GUI simply prevents actions taken within the GUI from being sent to Juju, and is _not_ additional security against the Juju API. - - - diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 8cc871858..54d428e88 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -33,9 +33,7 @@ navigation: - title: Administering Juju children: - - title: Juju users - location: users.md - - title: Scaling up and down + - title: Scaling applications location: charms-scaling.md - title: Upgrading applications location: charms-upgrading.md @@ -47,6 +45,8 @@ navigation: location: controllers-ha.md - title: Application high availability location: charms-ha.md + - title: Juju users + location: users.md - title: Advanced topics @@ -85,7 +85,7 @@ navigation: - title: Miscellaneous children: - - title: Juju GUI + - title: The Juju GUI location: controllers-gui.md - title: Disabling commands location: juju-block.md @@ -127,8 +127,6 @@ navigation: location: http://godoc.org/github.com/juju/juju/api - title: Status values location: reference-status.md - - title: Machine/unit numbering - location: reference-numbering.md - title: Contact us location: contact-us.md diff --git a/src/en/network-spaces.md b/src/en/network-spaces.md index 8693c0631..0975f14bc 100644 --- a/src/en/network-spaces.md +++ b/src/en/network-spaces.md @@ -1,7 +1,7 @@ -Title: Network Spaces +Title: Network spaces TODO: Bug tracking: https://bugs.launchpad.net/juju/+bug/1747998 -# Network Spaces +# Network spaces Juju models networks using *spaces*, which can be mapped to one or more subnets of the chosen backing cloud. When a space's subnets span multiple availability diff --git a/src/en/reference-numbering.md b/src/en/reference-numbering.md deleted file mode 100644 index 9366f1075..000000000 --- a/src/en/reference-numbering.md +++ /dev/null @@ -1,27 +0,0 @@ -Title: Machine and unit numbering -TODO: This page's contents should be merged with `add-machine` and `deploy` pages. - -# Machine and Unit numbering - -Within a model Juju keeps track of sequences for machines and units. -(Prior to 1.25 just machines). This means that for the life of a model, -the number associated with a machine will only ever increase. For example: - -```bash -juju add-machine # Add machine 0 -juju add-machine # Add machine 1 -juju terminate-machine # Remove machine 1 -juju add-machine # Add machine 2 -``` - -From 1.25 onwards unit numbering follows the same scheme. For each application -name the number will only every increase. For example: -```bash -juju deploy mongodb -n 2 # Adds units 0,1 -juju remove-application mongodb # Removed units 0,1 -juju deploy mongodb -n 2 # Adds units 2,3 -``` - -Prior to 1.25 units would only ever increase for a single application. If you -removed the application and created a new one of the same name the numbering -would start again from 0. From f435eeef21dd84808507699797a462c3983ffde4 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 15:06:25 -0400 Subject: [PATCH 076/311] copy file from master --- src/en/charms-config.md | 4 ++-- src/en/charms-deploying.md | 2 +- src/en/charms-destroy.md | 4 ++-- src/en/charms-fan.md | 4 ++-- src/en/controllers-gui.md | 5 +---- src/en/metadata.yaml | 10 ++++------ src/en/network-spaces.md | 4 ++-- 7 files changed, 14 insertions(+), 19 deletions(-) diff --git a/src/en/charms-config.md b/src/en/charms-config.md index 8f0ecc54e..2723223a0 100644 --- a/src/en/charms-config.md +++ b/src/en/charms-config.md @@ -1,6 +1,6 @@ -Title: Application configuration +Title: Configuring applications -# Application Configuration +# Configuring applications When deploying an application, the charm you use will often support or even require specific configuration options to be set. diff --git a/src/en/charms-deploying.md b/src/en/charms-deploying.md index c81179094..b0aa8b836 100644 --- a/src/en/charms-deploying.md +++ b/src/en/charms-deploying.md @@ -102,7 +102,7 @@ It is possible to deploy applications using local charms. See Deployed applications usually start with a sane default configuration. However, for some applications it may be desirable (and quicker) to configure them at deployment time. This can be done whether a charm is deployed from the Charm -Store or from a local charm. See [Application configuration][charms-config] for +Store or from a local charm. See [Configuring applications][charms-config] for more on this. ## Deploying to LXD containers diff --git a/src/en/charms-destroy.md b/src/en/charms-destroy.md index 4dcb930c5..03ab6d62a 100644 --- a/src/en/charms-destroy.md +++ b/src/en/charms-destroy.md @@ -1,8 +1,8 @@ -Title: Removing Juju objects +Title: Removing things TODO: remove-application|unit should mention in what circumstances the associated machine is removed (other units or containers will prevent this) remove-machine should mention in what circumstances the machine is not removed (other units or containers will prevent this) -# Removing Juju objects +# Removing things This section looks at how to remove the various objects you will encounter as you work with Juju. These are: diff --git a/src/en/charms-fan.md b/src/en/charms-fan.md index 4b9792512..8bc7ad7a2 100644 --- a/src/en/charms-fan.md +++ b/src/en/charms-fan.md @@ -1,9 +1,9 @@ -Title: Juju and Fan networking +Title: Fan container networking TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1733354 (remove constraints Note if no longer required) hardcoded: default AWS instance type of 'm3.medium' consider a third example: manually configure the Fan with Azure -# Juju and Fan networking +# Fan container networking Fan networking addresses a need raised by the proliferation of container usage in an IPv4 context: the ability to manage the address space such that network diff --git a/src/en/controllers-gui.md b/src/en/controllers-gui.md index 105760d91..22b75e3c5 100644 --- a/src/en/controllers-gui.md +++ b/src/en/controllers-gui.md @@ -15,7 +15,7 @@ comprise them, and the machines available. Additionally, the GUI can talk with the charm store in order to search, browse, and deploy charms to your environment. -# Using the GUI +## Using the GUI Juju GUI is now automatically included in every Juju controller after bootstrapping, thus eliminating the need to additionally deploy the Juju GUI @@ -191,6 +191,3 @@ monitoring type scenario. read-only mode in the GUI simply prevents actions taken within the GUI from being sent to Juju, and is _not_ additional security against the Juju API. - - - diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 8cc871858..54d428e88 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -33,9 +33,7 @@ navigation: - title: Administering Juju children: - - title: Juju users - location: users.md - - title: Scaling up and down + - title: Scaling applications location: charms-scaling.md - title: Upgrading applications location: charms-upgrading.md @@ -47,6 +45,8 @@ navigation: location: controllers-ha.md - title: Application high availability location: charms-ha.md + - title: Juju users + location: users.md - title: Advanced topics @@ -85,7 +85,7 @@ navigation: - title: Miscellaneous children: - - title: Juju GUI + - title: The Juju GUI location: controllers-gui.md - title: Disabling commands location: juju-block.md @@ -127,8 +127,6 @@ navigation: location: http://godoc.org/github.com/juju/juju/api - title: Status values location: reference-status.md - - title: Machine/unit numbering - location: reference-numbering.md - title: Contact us location: contact-us.md diff --git a/src/en/network-spaces.md b/src/en/network-spaces.md index 8693c0631..0975f14bc 100644 --- a/src/en/network-spaces.md +++ b/src/en/network-spaces.md @@ -1,7 +1,7 @@ -Title: Network Spaces +Title: Network spaces TODO: Bug tracking: https://bugs.launchpad.net/juju/+bug/1747998 -# Network Spaces +# Network spaces Juju models networks using *spaces*, which can be mapped to one or more subnets of the chosen backing cloud. When a space's subnets span multiple availability From f3520737c3d29b019eeb0d3bf7cf6b9005d0379d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 15 Oct 2018 15:57:58 -0400 Subject: [PATCH 077/311] edit based on GH feedback; add bug tracking --- src/en/metadata.yaml | 2 +- src/en/upgrade-series.md | 64 +++++++++++++++++++++++++++++++--------- 2 files changed, 51 insertions(+), 15 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 54d428e88..1870ba5d1 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -37,7 +37,7 @@ navigation: location: charms-scaling.md - title: Upgrading applications location: charms-upgrading.md - - title: Updating a machine series + - title: Upgrading a machine series location: upgrade-series.md - title: Controller backups location: controllers-backup.md diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index f0c12d659..3458fc6a6 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -1,7 +1,13 @@ -Title: Updating a machine series +Title: Upgrading a machine series TODO: warning: ubuntu code names hardcoded + bug tracking: https://bugs.launchpad.net/juju/+bug/1797399 + bug tracking: https://bugs.launchpad.net/juju/+bug/1797593 + bug tracking: https://bugs.launchpad.net/juju/+bug/1797595 + bug tracking: https://bugs.launchpad.net/juju/+bug/1797388 + bug tracking: https://bugs.launchpad.net/juju/+bug/1797396 + bug tracking: https://bugs.launchpad.net/juju/+bug/1797968 -# Updating a machine series +# Upgrading a machine series Starting with Juju `v.2.5.0`, to upgrade the series of a machine, the `upgrade-series` command is used. @@ -18,11 +24,8 @@ Here is an overview of the process: 1. The user initiates the upgrade. 1. The machine is removed from the pool of available machines in the sense that charms can not be deployed upon it. - 1. A minimum amount of the machine's software is upgraded and some changes - internal to Juju are made. + 1. Juju prepares the machine for the upcoming OS upgrade. 1. All units on the machine are taken into account. - 1. At the end of this step, from Juju's standpoint, the machine is now - running the target operating system. 1. The user manually performs the upgrade of the operating system and makes any other necessary changes. This should be accompanied by a maintenance window managed by the user. @@ -32,9 +35,10 @@ Here is an overview of the process: At no time does Juju take any action to prevent the machine from servicing workload client requests. -In the examples that follow, the machine in question has an ID of '1' and we'll -be moving from Ubuntu 16.04 LTS (Xenial) to Ubuntu 18.04 LTS (Bionic). - +In the examples that follow, the machine in question has an ID of '1', will +have one unit of 'apache2' deployed, and will be upgraded from Ubuntu 16.04 LTS +(Xenial) to Ubuntu 18.04 LTS (Bionic). + ### Initiating the upgrade You initiate the upgrade with the `prepare` sub-command, the machine ID, and @@ -47,20 +51,39 @@ juju upgrade-series prepare 1 bionic You will be asked to confirm the procedure. Use the `--agree` option to avoid this prompt. +Then output will be shown, such as: + +```no-highlight +leadership pinned for application "apache2" +machine-1 started upgrade series from series xenial to series bionic +apache2/0 pre-series-upgrade hook running +apache2/0 pre-series-upgrade not found, skipping +machine-1 all necessary binaries and service files written + +Juju is now ready for the series to be updated. +Perform any manual steps required along with "do-release-upgrade". +When ready run the following to complete the upgrade series process: + +juju upgrade-series complete 1 +``` + All charms associated with the machine must support the target series in order for the command to complete successfully. An error will be emitted otherwise. +There is a `--force` option available but it should be used with caution. The deployed charms will be inspected for a 'pre-series-upgrade' hook. If such -a hook exists, it will be run. +a hook exists, it will be run. In our example, such a hook was not found in the +charm. ### Upgrading the operating system One important step in upgrading the operating system is the upgrade of all -software packages. Apply the standard `do-release-upgrade` command to the -machine via SSH: +software packages. To do this, log in to the machine via SSH and apply the +standard `do-release-upgrade` command: ```bash -juju ssh 1 do-release-upgrade +juju ssh 1 +$ do-release-upgrade ``` As a resource, use the [Ubuntu Server Guide][serverguide-upgrade]. Also be sure @@ -77,8 +100,21 @@ that's done, tell Juju that the machine is ready: juju upgrade-series complete 1 ``` +Sample output: + +```no-highlight +machine-1 complete phase started +machine-1 starting all unit agents after series upgrade +apache2/0 post-series-upgrade hook running +apache2/0 post-series-upgrade not found, skipping +leadership unpinned for application "apache2" + +Upgrade series for machine "1" has successfully completed +``` + Deployed charms will be inspected for a 'post-series-upgrade' hook. If such a -hook exists, it will be run. +hook exists, it will be run. In our example, such a hook was not found in the +charm. You're done. The machine is now fully upgraded and is an active Juju machine. From c97e5e5e19211bfb95aec485f3a5555bd61779b8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 16 Oct 2018 09:47:58 -0400 Subject: [PATCH 078/311] edit based on GH feedback; minor changes; bug tracking --- src/en/upgrade-series.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 3458fc6a6..e25cb5171 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -6,16 +6,17 @@ TODO: warning: ubuntu code names hardcoded bug tracking: https://bugs.launchpad.net/juju/+bug/1797388 bug tracking: https://bugs.launchpad.net/juju/+bug/1797396 bug tracking: https://bugs.launchpad.net/juju/+bug/1797968 + bug tracking: https://bugs.launchpad.net/juju/+bug/1798094 + bug tracking: https://bugs.launchpad.net/juju/+bug/1798097 # Upgrading a machine series Starting with Juju `v.2.5.0`, to upgrade the series of a machine, the `upgrade-series` command is used. -!!! Important: - The `upgrade-series` command does not support upgrading a controller. See - below section [Upgrading a controller machine][#upgrading-a-controller] for - how to do that using an alternate method. +The `upgrade-series` command does not support upgrading a controller. See below +section [Upgrading a controller machine][#upgrading-a-controller] for how to do +that using an alternate method. ## Upgrading a workload machine @@ -23,7 +24,7 @@ Here is an overview of the process: 1. The user initiates the upgrade. 1. The machine is removed from the pool of available machines in the sense - that charms can not be deployed upon it. + that charms can not be deployed to it. 1. Juju prepares the machine for the upcoming OS upgrade. 1. All units on the machine are taken into account. 1. The user manually performs the upgrade of the operating system and makes @@ -35,9 +36,9 @@ Here is an overview of the process: At no time does Juju take any action to prevent the machine from servicing workload client requests. -In the examples that follow, the machine in question has an ID of '1', will -have one unit of 'apache2' deployed, and will be upgraded from Ubuntu 16.04 LTS -(Xenial) to Ubuntu 18.04 LTS (Bionic). +In the examples that follow, the machine in question has an ID of '1', has one +unit of 'apache2' deployed, and will be upgraded from Ubuntu 16.04 LTS (Xenial) +to Ubuntu 18.04 LTS (Bionic). ### Initiating the upgrade @@ -48,8 +49,8 @@ the target series: juju upgrade-series prepare 1 bionic ``` -You will be asked to confirm the procedure. Use the `--agree` option to avoid -this prompt. +You will be asked to confirm the procedure. Use the `-y` option to avoid this +prompt. Then output will be shown, such as: From 8ff220197b6435b18b90556201bed9decae1afe8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 16 Oct 2018 09:55:45 -0400 Subject: [PATCH 079/311] trivial --- src/en/upgrade-series.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index e25cb5171..da0911d7f 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -23,15 +23,14 @@ that using an alternate method. Here is an overview of the process: 1. The user initiates the upgrade. - 1. The machine is removed from the pool of available machines in the sense - that charms can not be deployed to it. + 1. The machine is no longer available for charm deployments. 1. Juju prepares the machine for the upcoming OS upgrade. 1. All units on the machine are taken into account. 1. The user manually performs the upgrade of the operating system and makes any other necessary changes. This should be accompanied by a maintenance window managed by the user. 1. The user informs Juju that the machine has been successfully upgraded. The - machine is reinserted into the machine pool. + machine becomes available for charm deployments. At no time does Juju take any action to prevent the machine from servicing workload client requests. From 6f4a8c3d924b6e68212bc7a40a5367bf25d8372e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 16 Oct 2018 13:03:42 -0400 Subject: [PATCH 080/311] add links --- src/en/index.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/en/index.md b/src/en/index.md index 96f990052..b68317049 100644 --- a/src/en/index.md +++ b/src/en/index.md @@ -26,8 +26,9 @@ homepage: true

What's new

@@ -35,6 +36,11 @@ homepage: true
From f31a121c94c260c555ce1bf73463f20ac4ae8674 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 19 Oct 2018 14:44:27 -0400 Subject: [PATCH 081/311] add section --- src/en/clouds-lxd-advanced.md | 44 ++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 656a1a241..3a5df2d53 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -9,6 +9,7 @@ The topics presented here are: - LXD clustering - Adding a remote LXD cloud + - Charms and LXD profiles ## LXD clustering @@ -48,7 +49,7 @@ See the upstream documentation on [Clustering][lxd-upstream-clustering]. ## Adding a remote LXD cloud The traditional way of using LXD with Juju is by having both the Juju client -and the LXD daemon local to each other. However, since `v.2.5` Juju supports +and the LXD daemon local to each other. However, since `v.2.5.0` Juju supports connecting to a remote LXD daemon. Doing so does not require LXD to be installed alongside the Juju client. @@ -214,6 +215,46 @@ Now that the cloud and credentials have been added the next step is to create a controller. See [Creating a controller][clouds-lxd-creating-a-controller] on the main LXD page. +## Charms and LXD profiles + +Juju (`v.2.5.0`) has the following functionality for those charms that make use +of LXD profiles: + + - A validity check is performed on the profile(s) during the deployment of the + charm. This is based on a hardcoded allow/deny list. The `--force` option + can be used to bypass this check but this is not recommended. + - A profile is upgraded during the upgrade of the charm + (`juju upgrade-charm`). + - A profile is exposed at the machine level by using either the `show-machine` + command or the `status --format=yaml` command. + +Here is partial output from either of the above two commands that shows the +type of profile information that can be extracted from Juju: + +```no-highlight + lxd-profiles: + juju-default-lxd-profile-0: + config: + environment.http_proxy: "" + linux.kernel_modules: openvswitch,nbd,ip_tables,ip6_tables + security.nesting: "true" + security.privileged: "true" + description: lxd profile for testing, black list items grouped commented out + devices: + bdisk: + source: /dev/loop0 + type: unix-block + sony: + productid: 51da + type: usb + vendorid: 0fce + tun: + path: /dev/net/tun + type: unix-char +``` + +See the upstream documentation on [LXD profiles][lxd-upstream-profiles]. + @@ -225,4 +266,5 @@ the main LXD page. [credentials]: ./credentials.md [clouds-lxd-creating-a-controller]: ./clouds-LXD.md#creating-a-controller [lxd-upstream-clustering]: https://lxd.readthedocs.io/en/latest/clustering/ +[lxd-upstream-profiles]: https://lxd.readthedocs.io/en/latest/profiles/ [deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines From 93fca560d08bcc523f8b6122cf19263584b6fe39 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 19 Oct 2018 16:58:49 -0400 Subject: [PATCH 082/311] add allowed list of profile thingies --- src/en/clouds-lxd-advanced.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 3a5df2d53..6edd37531 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -221,15 +221,30 @@ Juju (`v.2.5.0`) has the following functionality for those charms that make use of LXD profiles: - A validity check is performed on the profile(s) during the deployment of the - charm. This is based on a hardcoded allow/deny list. The `--force` option - can be used to bypass this check but this is not recommended. + charm. This is based on a hardcoded list of allowed items, everything else + being denied. The `--force` option can be used to bypass this check but this + is not recommended. The list is: + +```no-highlight +config + -boot + -limits + -migration + +devices + unix-char + unix-block + gpu + usb +``` + - A profile is upgraded during the upgrade of the charm (`juju upgrade-charm`). - A profile is exposed at the machine level by using either the `show-machine` command or the `status --format=yaml` command. Here is partial output from either of the above two commands that shows the -type of profile information that can be extracted from Juju: +type of profile information that is surfaced: ```no-highlight lxd-profiles: From 8b84a6b090f905226de306626c7ef5c06bdb736e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 19 Oct 2018 18:56:54 -0400 Subject: [PATCH 083/311] minor reword --- src/en/clouds-lxd-advanced.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 6edd37531..0980ef113 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -243,8 +243,8 @@ devices - A profile is exposed at the machine level by using either the `show-machine` command or the `status --format=yaml` command. -Here is partial output from either of the above two commands that shows the -type of profile information that is surfaced: +This is an example of the kind of LXD profile information that can be obtained +from either of the above two commands: ```no-highlight lxd-profiles: From 439ccb7a300bcbea7d7cd2161f48f8c0d033d127 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 19 Oct 2018 19:00:28 -0400 Subject: [PATCH 084/311] trivial --- src/en/clouds-lxd-advanced.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 0980ef113..c3be418b7 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -241,10 +241,8 @@ devices - A profile is upgraded during the upgrade of the charm (`juju upgrade-charm`). - A profile is exposed at the machine level by using either the `show-machine` - command or the `status --format=yaml` command. - -This is an example of the kind of LXD profile information that can be obtained -from either of the above two commands: + command or the `status --format=yaml` command. Below is an example of the + kind of information that can be obtained from either of these two commands: ```no-highlight lxd-profiles: From 4fd13b83f434dc3a1de46660a570b77ea7e345bc Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 19 Oct 2018 19:19:09 -0400 Subject: [PATCH 085/311] link from main page; move latter list up the page --- src/en/clouds-LXD.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/en/clouds-LXD.md b/src/en/clouds-LXD.md index 38bc7b3f1..172cc020f 100644 --- a/src/en/clouds-LXD.md +++ b/src/en/clouds-LXD.md @@ -20,6 +20,13 @@ bound to the LXD cloud type (i.e. they can affect containers that are themselves backed by a Juju machine running on any cloud type). See [Constraints and LXD containers][charms-constraints-lxd] for details. +Here is a list of advanced LXD features supported by Juju that are explained on +a separate page: + + - [LXD clustering][clouds-lxd-advanced-cluster] (`v.2.4.0`) + - [Adding a remote LXD cloud][clouds-lxd-advanced-remote] (`v.2.5.0`) + - [Charms and LXD profiles][clouds-lxd-advanced-profiles] (`v.2.5.0`) + ## Software prerequisites Both LXD and Juju will be needed on the host system. @@ -169,13 +176,6 @@ Output: +---------------+---------+----------------------+------+------------+-----------+ ``` -## Advanced LXD support - -Here is a list of advanced LXD features supported by Juju: - - - [LXD clustering][clouds-lxd-advanced-cluster] (`v.2.4.0`) - - [Adding a remote LXD cloud][clouds-lxd-advanced-remote] (`v.2.5.0`) - ## Additional LXD resources [Additional LXD resources][clouds-lxd-resources] provides more LXD-specific @@ -205,6 +205,7 @@ See these pages for ideas on what to do next: [clouds-lxd-resources]: ./clouds-lxd-resources.md [clouds-lxd-advanced-cluster]: ./clouds-lxd-advanced.md#lxd-clustering [clouds-lxd-advanced-remote]: ./clouds-lxd-advanced.md#adding-a-remote-lxd-cloud +[clouds-lxd-advanced-profiles]: ./clouds-lxd-advanced.md#charms-and-lxd-profiles [lxd-snap]: ./clouds-lxd-resources.md#using-the-lxd-snap [ubuntu-lxd]: http://www.ubuntu.com/cloud/lxd [charms-constraints-lxd]: ./charms-constraints.md#constraints-and-lxd-containers From bff86412dd7e4c805fcedb68a74df5e8c91d5d56 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 22 Oct 2018 14:38:32 -0400 Subject: [PATCH 086/311] edit based on GH review --- src/en/clouds-lxd-advanced.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index c3be418b7..3c5b41461 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -217,8 +217,9 @@ the main LXD page. ## Charms and LXD profiles -Juju (`v.2.5.0`) has the following functionality for those charms that make use -of LXD profiles: +Juju (`v.2.5.0`) allows charms to include a LXD profile. The profile will be +applied to a LXD container that the charm is deployed into. The following +functionality is built in: - A validity check is performed on the profile(s) during the deployment of the charm. This is based on a hardcoded list of allowed items, everything else @@ -238,11 +239,12 @@ devices usb ``` - - A profile is upgraded during the upgrade of the charm + - Profiles are upgraded during the upgrade of the charm (`juju upgrade-charm`). - - A profile is exposed at the machine level by using either the `show-machine` - command or the `status --format=yaml` command. Below is an example of the - kind of information that can be obtained from either of these two commands: + - Profiles are displayed at the machine level by using either the + `show-machine` command or the `status --format=yaml` command. Below is an + example of the kind of information that can be obtained from either of these + two commands: ```no-highlight lxd-profiles: From f883de9a3bfbff73ae54ef849a48163b2218e360 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 22 Oct 2018 16:43:01 -0400 Subject: [PATCH 087/311] review and add command --- src/en/credentials.md | 156 ++++++++++++++++++++++++------------------ 1 file changed, 90 insertions(+), 66 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 8df5631df..7488425ff 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -13,57 +13,51 @@ We use the term *credentials* to describe the material necessary to do this represented by a *credential name* that is used to refer to those credentials in subsequent commands. -Juju selects a credential according to how many credentials are defined. If you -have only one credential, or if a credential is labelled 'default', then this -is the credential that will be used by Juju. When multiple credentials are -defined, with no default, a credential name must be specified at the model -level. - +When credentials are added for a given cloud they become available to use on +that cloud's controller and models. There are therefore two categories of +credentials: those that are available (local) and those that have been sent to +a controller (remote) due to requiring a credential for the first time. + +An active credential (one that has been used to bring about a change in Juju) +is always associated with a cloud, a Juju user, and a model. + ## Adding credentials Juju supports three methods for adding credentials: - - Accepting credentials provided interactively by the user on the command line - - Scanning for existing credentials via environment variables and/or "rc" + - accepting credentials provided interactively by the user on the command line + - scanning for existing credentials via environment variables and/or "rc" files (only supported by certain providers) - - Reading a user-provided [YAML-formatted][yaml] file + - reading a user-provided [YAML-formatted][yaml] file !!! Note: - LXD deployments are a special case. Accessed from a Juju admin user, they - do not require credentials. Accessed from a non-admin user, a *certificate - credential* is needed. See + Local LXD deployments are a special case. Accessed from a Juju admin user, + they do not require credentials. Accessed from a non-admin user, a + *certificate credential* is needed. See [Additional LXD resources][clouds-lxd-resources-non-admin-creds] for details. ### Adding credentials interactively -You can add credentials interactively in this way: +You can add credentials interactively. To do so with the AWS cloud: ```bash -juju add-credential +juju add-credential aws ``` -You will be asked for credential information based on the chosen cloud. Here -we're adding credentials for cloud 'aws': +You will be asked for credential information based on the chosen cloud. For our +AWS cloud the resulting interactive session would look like: ```no-highlight Enter credential name: carol Using auth-type "access-key". Enter access-key: ******* Enter secret-key: ******* -Credentials added for cloud aws. -``` - -If you eventually set multiple credential names for the same cloud you will -need to set one as the default: - -```bash -juju set-default-credential ``` -The default credential will be used when creating a controller with the -`bootstrap` command. Otherwise, a credential can be specified with the -`--credential` option with both the `bootstrap` and `add-model` commands. +If you end up adding multiple credentials for the same cloud you will need to +set one as the default. See below section +[Setting default credentials][#setting-default-credentials]. ### Adding credentials from environment variables @@ -213,20 +207,48 @@ juju add-credential azure -f mycreds.yaml ## Managing credentials -There are several management tasks that can be done related to credentials. +There are several management tasks that can be done related to credentials: -### Listing credentials + - Setting default credentials + - Listing local credentials + - Listing remote credentials + - Updating local credentials + - Updating remote credentials + - Removing local credentials + - Setting a remote credential for a model -When credentials are added to Juju they become available to use on a controller -and its models. There are therefore two categories of credentials: those that -are available and those that are currently in use. +### Setting default credentials + +To set the default credential for a cloud: -#### Available +```bash +juju set-default-credential aws carol +``` -You can display what credentials are available by running the command: +If only one credential exists for a cloud, it becomes the effective default +credential for that cloud. + +Setting a default affects operations that require a credential such as creating +a controller (`bootstrap`) and adding a model (`add-model`). It does not change +what is currently in use (on a controller). With both these commands a +credential can be specified with the `--credential` option. + +A default must be defined if multiple credentials exist for a given cloud. +Failure to do so will cause an error to be emitted from those commands that +require a credential: + +```no-highlight +ERROR more than one credential is available +specify a credential using the --credential argument +``` + +### Listing local credentials + +You can display what credentials are available by running the +`credentials` command: ```bash -juju list-credentials +juju credentials ``` Sample output: @@ -239,13 +261,13 @@ aws bob*, carol google wayne ``` -The asterisk '*' denotes the default credential, which will be used for the -named cloud unless another is specified. +The asterisk denotes the default credential, which will be used for the named +cloud unless another is specified. To reveal actual authentication material (e.g. passwords, keys): ```bash -juju list-credentials --format yaml --show-secrets +juju credentials --format yaml --show-secrets ``` Sample output: @@ -262,9 +284,10 @@ local-credentials: Notice how the output says 'local-credentials', meaning they are stored on the local Juju client. -#### In use +### Listing remote credentials -To see what credentials are in use by a model (here the 'default' model): +To see what credentials are in use by a model (here the 'default' model) the +`show-model` command can be used: ```bash juju show-model default @@ -286,9 +309,9 @@ default: The `models --format yaml` command also shows this information, albeit for all models. -The above commands do not display authentication material. To view the active -credentials, including the cloud name, credential names, and the names of -models: +The above commands do not display authentication material. Use the +`show-credentials` command to view the active credentials, including the cloud +name, credential names, and model names: ```bash juju show-credentials --show-secrets @@ -314,22 +337,6 @@ the controller. The `show-credentials` command queries the controller to get its information. -### Setting default credentials - -You can set the default credential for a cloud: - -```bash -juju set-default-credential aws carol -``` - -Notes: - - - This affects operations that require a newly-input credential (e.g. - `juju add-model`). In particular, it does not change what is currently in - use (on a controller). - - If only one credential name exists, it will become the effective default - credential. - ### Updating local credentials To update an existing credential locally use the `add-credential` command with @@ -341,8 +348,9 @@ Here we decided to use the file 'mycreds.yaml' from a previous example: juju add-credential aws -f mycreds.yaml --replace ``` -This will overwrite existing credential information, so make sure all current -credentials are contained in the file, not just the new or changed one. +This will overwrite **all** existing credentials for that cloud, so make sure +all current credentials are contained in the file, not just the new or changed +one. Updating credentials in this way does not update credentials currently in use (on an existing controller/cloud). See the next section for that. The @@ -372,7 +380,7 @@ juju add-credential --replace joe juju update-credential google joe ``` -#### Updating remote credentials using a different Juju user +#### Updating remote credentials using a different Juju user If you are unable to ascertain the original Juju username then you will need to use a different one. This implies adding a new credential name, copying over @@ -417,18 +425,31 @@ Credentials: ### Removing local credentials -If a local credential (i.e. not cached on a controller) is no longer required, -it can be removed: +The `remove-credential` command is used to remove a local credential (i.e. not +cached on a controller): ```bash juju remove-credential aws bob ``` +### Setting a remote credential for a model + +To set what remote credential should be used for a model the `set-credential` +command (`v.2.5.0`) is available. For instance, to have remote credential 'bob' +be used for model 'trinity' (for cloud 'aws'): + +```bash +juju set-credential -m trinity aws bob +``` + +!!! Note: + If the stated credential does not exist remotely but it does locally then + the local credential will be sent to the controller. The command will error + out if the credential is neither remote nor local. + -[yaml]: http://www.yaml.org/spec/1.2/spec.html -[clouds-lxd-resources-non-admin-creds]: ./clouds-lxd-resources.md#non-admin-user-credentials [clouds-aws]: ./help-aws.md [clouds-azure]: ./help-azure.md [clouds-google]: ./help-google.md @@ -438,7 +459,10 @@ juju remove-credential aws bob [clouds-oracle]: ./help-oracle.md [clouds-openstack]: ./help-openstack.md [clouds-vmware]: ./help-vmware.md +[yaml]: http://www.yaml.org/spec/1.2/spec.html +[clouds-lxd-resources-non-admin-creds]: ./clouds-lxd-resources.md#non-admin-user-credentials [clouds-aws-using-env-variables]: help-aws.md#using-environment-variables [clouds-google-using-env-variables]: help-google.md#using-environment-variables [clouds-openstack-using-env-variables]: help-openstack.md#using-environment-variables [clouds-adding-clouds-manually]: ./clouds.md#adding-clouds-manually +[#setting-default-credentials]: #setting-default-credentials From 858a3dab957fe98ec6844ad32a14f5d55b5fc16a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 22 Oct 2018 18:41:31 -0400 Subject: [PATCH 088/311] added material --- src/en/whats-new.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/src/en/whats-new.md b/src/en/whats-new.md index cefef17e1..1a1f7a1ea 100644 --- a/src/en/whats-new.md +++ b/src/en/whats-new.md @@ -50,7 +50,17 @@ procedure. See [][]. -## CLI bundle export support +## Charm support for LXD profiles + +Juju now supports charms that include a LXD profile. A profile is applied +to a LXD container that the charm is deployed into. Some hardcoded security +checks are applied automatically when such a charm is deployed and profile +information is exposed at the machine level with the `status` and +`show-machine` commands. + +See [][]. + +## New command for saving a bundle A model's configuration can now be saved as a bundle at the command line using the new `export-bundle` command. Previously, the Juju GUI was needed to save @@ -58,7 +68,7 @@ a bundle. See [][]. -## New tool for comparing a bundle and model +## New command for comparing a bundle and model A model and a bundle can now be compared using the new `diff-bundle` command. @@ -77,19 +87,17 @@ recognises certain environment variables used by OpenStack - typically via its See [][]. -## Charm Store controller configuration key added +## New command for assigning a remote credential to a model -A custom Charm Store can be configured by specifying a URL during the creation -of a controller (`bootstrap`). +Occasionally there is the need to change (or set) what remote credential is +assigned to a model. This is now possible via the new `set-credential` command. See [][]. -## Charm support for LXD profiles +## Charm Store controller configuration key added - -??????? -`status --format yaml` -`show-machines` +A custom Charm Store can be configured by specifying a URL during the creation +of a controller (`bootstrap`). See [][]. From b7c519e102ef035619e69e876c3efec948eab1f4 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 22 Oct 2018 18:56:45 -0400 Subject: [PATCH 089/311] add internal links; slight rewording --- src/en/credentials.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 7488425ff..05c1c70a7 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -207,15 +207,15 @@ juju add-credential azure -f mycreds.yaml ## Managing credentials -There are several management tasks that can be done related to credentials: +Here we cover the management of credentials. - - Setting default credentials - - Listing local credentials - - Listing remote credentials - - Updating local credentials - - Updating remote credentials - - Removing local credentials - - Setting a remote credential for a model + - [Setting default credentials][#setting-default-credentials] + - [Listing local credentials][#listing-local-credentials] + - [Listing remote credentials][#listing-remote-credentials] + - [Updating local credentials][#updating-local-credentials] + - [Updating remote credentials][#updating-remote-credentials] + - [Removing local credentials][#removing-local-credentials] + - [Setting a remote credential for a model][#setting-a-remote-credential-for-a-model] ### Setting default credentials @@ -465,4 +465,11 @@ juju set-credential -m trinity aws bob [clouds-google-using-env-variables]: help-google.md#using-environment-variables [clouds-openstack-using-env-variables]: help-openstack.md#using-environment-variables [clouds-adding-clouds-manually]: ./clouds.md#adding-clouds-manually + [#setting-default-credentials]: #setting-default-credentials +[#listing-local-credentials]: #listing-local-credentials] +[#listing-remote-credentials]: #listing-remote-credentials +[#updating-local-credentials]: #updating-local-credentials +[#updating-remote-credentials]: #updating-remote-credentials +[#removing-local-credentials]: #removing-local-credentials +[#setting-a-remote-credential-for-a-model]: #setting-a-remote-credential-for-a-model From 66293f3c03f351f47266ca457bae945019eae3f0 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 23 Oct 2018 10:51:14 -0400 Subject: [PATCH 090/311] edit based on GH review --- src/en/credentials.md | 46 ++++++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 05c1c70a7..76bce2d14 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -15,8 +15,8 @@ in subsequent commands. When credentials are added for a given cloud they become available to use on that cloud's controller and models. There are therefore two categories of -credentials: those that are available (local) and those that have been sent to -a controller (remote) due to requiring a credential for the first time. +credentials: those that are available (local) and those that have been uploaded +to a controller (remote) due to requiring a credential for the first time. An active credential (one that has been used to bring about a change in Juju) is always associated with a cloud, a Juju user, and a model. @@ -207,7 +207,7 @@ juju add-credential azure -f mycreds.yaml ## Managing credentials -Here we cover the management of credentials. +The following credential management tasks are covered: - [Setting default credentials][#setting-default-credentials] - [Listing local credentials][#listing-local-credentials] @@ -215,7 +215,7 @@ Here we cover the management of credentials. - [Updating local credentials][#updating-local-credentials] - [Updating remote credentials][#updating-remote-credentials] - [Removing local credentials][#removing-local-credentials] - - [Setting a remote credential for a model][#setting-a-remote-credential-for-a-model] + - [Changing a remote credential for a model][#changing-a-remote-credential-for-a-model] ### Setting default credentials @@ -261,8 +261,9 @@ aws bob*, carol google wayne ``` -The asterisk denotes the default credential, which will be used for the named -cloud unless another is specified. +An asterisk denotes a default credential. In the above output, credential 'bob' +is the default for cloud 'aws' and no default has been specified for cloud +'google'. Default credentials are covered in more depth later on. To reveal actual authentication material (e.g. passwords, keys): @@ -286,7 +287,7 @@ the local Juju client. ### Listing remote credentials -To see what credentials are in use by a model (here the 'default' model) the +To see what credential is in use by a model (here the 'default' model) the `show-model` command can be used: ```bash @@ -348,9 +349,13 @@ Here we decided to use the file 'mycreds.yaml' from a previous example: juju add-credential aws -f mycreds.yaml --replace ``` -This will overwrite **all** existing credentials for that cloud, so make sure -all current credentials are contained in the file, not just the new or changed -one. +Any existing credential will be overwritten by an identically named credential +in the file. As a safeguard to inadvertently overwriting credentials, an error +will be emitted if the `--replace` option is not used: + +```no-highlight +ERROR local credentials for cloud "aws" already exist; use --replace to overwrite / merge +``` Updating credentials in this way does not update credentials currently in use (on an existing controller/cloud). See the next section for that. The @@ -432,11 +437,12 @@ cached on a controller): juju remove-credential aws bob ``` -### Setting a remote credential for a model +### Changing a remote credential for a model -To set what remote credential should be used for a model the `set-credential` -command (`v.2.5.0`) is available. For instance, to have remote credential 'bob' -be used for model 'trinity' (for cloud 'aws'): +To change what remote credential should be used for a model the +`set-credential` command (`v.2.5.0`) is available to the controller admin or +the model owner. For instance, to have remote credential 'bob' be used for +model 'trinity' (for cloud 'aws'): ```bash juju set-credential -m trinity aws bob @@ -444,8 +450,8 @@ juju set-credential -m trinity aws bob !!! Note: If the stated credential does not exist remotely but it does locally then - the local credential will be sent to the controller. The command will error - out if the credential is neither remote nor local. + the local credential will be uploaded to the controller. The command will + error out if the credential is neither remote nor local. @@ -461,9 +467,9 @@ juju set-credential -m trinity aws bob [clouds-vmware]: ./help-vmware.md [yaml]: http://www.yaml.org/spec/1.2/spec.html [clouds-lxd-resources-non-admin-creds]: ./clouds-lxd-resources.md#non-admin-user-credentials -[clouds-aws-using-env-variables]: help-aws.md#using-environment-variables -[clouds-google-using-env-variables]: help-google.md#using-environment-variables -[clouds-openstack-using-env-variables]: help-openstack.md#using-environment-variables +[clouds-aws-using-env-variables]: ./help-aws.md#using-environment-variables +[clouds-google-using-env-variables]: ./help-google.md#using-environment-variables +[clouds-openstack-using-env-variables]: ./help-openstack.md#using-environment-variables [clouds-adding-clouds-manually]: ./clouds.md#adding-clouds-manually [#setting-default-credentials]: #setting-default-credentials @@ -472,4 +478,4 @@ juju set-credential -m trinity aws bob [#updating-local-credentials]: #updating-local-credentials [#updating-remote-credentials]: #updating-remote-credentials [#removing-local-credentials]: #removing-local-credentials -[#setting-a-remote-credential-for-a-model]: #setting-a-remote-credential-for-a-model +[#changing-a-remote-credential-for-a-model]: #changing-a-remote-credential-for-a-model From c3874a162c52b9fa7262355696164205d897105f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 24 Oct 2018 09:32:58 -0400 Subject: [PATCH 091/311] precision --- src/en/credentials.md | 47 +++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 76bce2d14..393ab86ba 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -15,11 +15,14 @@ in subsequent commands. When credentials are added for a given cloud they become available to use on that cloud's controller and models. There are therefore two categories of -credentials: those that are available (local) and those that have been uploaded -to a controller (remote) due to requiring a credential for the first time. - -An active credential (one that has been used to bring about a change in Juju) -is always associated with a cloud, a Juju user, and a model. +credentials: those that are available to the Juju client (local) and those that +are active and have been uploaded to a controller (remote). A credential +becomes active when it is needed to bring about a change in Juju for the first +time. + +An active credential is always associated with one cloud, one Juju user, and +one, or more, models. A model, however, is always linked to a single +credential. ## Adding credentials @@ -39,7 +42,8 @@ Juju supports three methods for adding credentials: ### Adding credentials interactively -You can add credentials interactively. To do so with the AWS cloud: +To add credentials interactively use the `add-credential` command. To do so +with the AWS cloud: ```bash juju add-credential aws @@ -78,19 +82,15 @@ call the credential set. You will need to rescan the variables if their values ever change. A scan only picks up *current* values. -There are three providers that use tools that support this variables method: - -[Amazon AWS][clouds-aws-using-env-variables] | -[Google GCE][clouds-google-using-env-variables] | -[OpenStack][clouds-openstack-using-env-variables] - -Each page provides details on using this method with its respective provider. +There are three providers that use tools that support this method: +[Amazon AWS][clouds-aws-using-env-variables], +[Google GCE][clouds-google-using-env-variables], and +[OpenStack][clouds-openstack-using-env-variables]. -!!! Note: - The `autoload-credentials` command is also used to generate a certificate - credential for localhost clouds. This is needed for providing access to - non-admin Juju users. See - [Additional LXD resources][clouds-lxd-resources-non-admin-creds]. +The `autoload-credentials` command is also used to generate a certificate +credential for localhost clouds. This is needed for providing access to +non-admin Juju users. See +[Additional LXD resources][clouds-lxd-resources-non-admin-creds]. ### Adding credentials from a file @@ -385,6 +385,9 @@ juju add-credential --replace joe juju update-credential google joe ``` +The `update-credential` command is the only command that can alter a credential +cached on a controller. + #### Updating remote credentials using a different Juju user If you are unable to ascertain the original Juju username then you will need @@ -439,10 +442,10 @@ juju remove-credential aws bob ### Changing a remote credential for a model -To change what remote credential should be used for a model the -`set-credential` command (`v.2.5.0`) is available to the controller admin or -the model owner. For instance, to have remote credential 'bob' be used for -model 'trinity' (for cloud 'aws'): +To change what remote credential is used for a model the `set-credential` +command (`v.2.5.0`) is available to the controller admin or the model owner. +For instance, to have remote credential 'bob' be used for model 'trinity' (for +cloud 'aws'): ```bash juju set-credential -m trinity aws bob From 77ea56aa63f8a3e5b23f62f0a8fe1b94c4ecd518 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 24 Oct 2018 10:16:50 -0400 Subject: [PATCH 092/311] small improvements --- src/en/credentials.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index 393ab86ba..ca38d5842 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -34,12 +34,14 @@ Juju supports three methods for adding credentials: - reading a user-provided [YAML-formatted][yaml] file !!! Note: - Local LXD deployments are a special case. Accessed from a Juju admin user, - they do not require credentials. Accessed from a non-admin user, a - *certificate credential* is needed. See - [Additional LXD resources][clouds-lxd-resources-non-admin-creds] for + A local LXD cloud is a special case. When accessed from a Juju admin user, + a credential does not need to be added; a 10-yr certificate is set up + for you. However, when accessed from a non-admin user this is not the case. + See [Additional LXD resources][clouds-lxd-resources-non-admin-creds] for details. +Added credentials get saved to file `~/.local/share/juju/credentials.yaml`. + ### Adding credentials interactively To add credentials interactively use the `add-credential` command. To do so @@ -49,14 +51,19 @@ with the AWS cloud: juju add-credential aws ``` -You will be asked for credential information based on the chosen cloud. For our -AWS cloud the resulting interactive session would look like: +You will be asked for information based on the chosen cloud. For the AWS cloud +the resulting interactive session looks like: ```no-highlight Enter credential name: carol + Using auth-type "access-key". -Enter access-key: ******* -Enter secret-key: ******* + +Enter access-key: AKBAICUYUPFXID2GHC5S + +Enter secret-key: *********************** (does not echo back) + +Credential "carol" added locally for cloud "aws". ``` If you end up adding multiple credentials for the same cloud you will need to From df4b752c4533e4cf0e6df23594562167d2f0084c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 26 Oct 2018 12:19:29 -0400 Subject: [PATCH 093/311] edit README.md --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 4677172c2..86c88e140 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,16 @@ # Documentation for Juju +** +THESE INSTRUCTIONS ARE OBSOLETE. +WORKAROUND: APPLY THE MAAS PROJECT CONTRIBUTOR PAGES TO JUJU: + +https://github.com/CanonicalLtd/maas-docs + +JUJU DOCUMENTATION WILL ALSO SOON BE MOVING TO DISCOURSE: + +https://discourse.jujucharms.com +** + The documentation is written in Markdown, and then generated into HTML. The latest version of these docs live at: From b3a8860f0b7a3566f1a62011f7486dd91cd65ff3 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 26 Oct 2018 12:24:40 -0400 Subject: [PATCH 094/311] edit README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 86c88e140..8c30dc73e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Documentation for Juju -** THESE INSTRUCTIONS ARE OBSOLETE. + WORKAROUND: APPLY THE MAAS PROJECT CONTRIBUTOR PAGES TO JUJU: https://github.com/CanonicalLtd/maas-docs @@ -9,7 +9,8 @@ https://github.com/CanonicalLtd/maas-docs JUJU DOCUMENTATION WILL ALSO SOON BE MOVING TO DISCOURSE: https://discourse.jujucharms.com -** + +----- The documentation is written in Markdown, and then generated into HTML. From 5697e0d54aabc4bb9c326b3f90406088b670ce8c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 26 Oct 2018 16:08:48 -0400 Subject: [PATCH 095/311] edit README with more details --- README.md | 203 +++++++++++++++++++++++++++--------------------------- 1 file changed, 100 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 8c30dc73e..182b86da6 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,11 @@ # Documentation for Juju -THESE INSTRUCTIONS ARE OBSOLETE. - -WORKAROUND: APPLY THE MAAS PROJECT CONTRIBUTOR PAGES TO JUJU: - -https://github.com/CanonicalLtd/maas-docs - -JUJU DOCUMENTATION WILL ALSO SOON BE MOVING TO DISCOURSE: +JUJU DOCUMENTATION WILL SOON BE MOVING TO DISCOURSE: https://discourse.jujucharms.com +RENDERING THESE INSTRUCTIONS OBSOLETE. + ----- The documentation is written in Markdown, and then generated into HTML. @@ -17,70 +13,106 @@ The documentation is written in Markdown, and then generated into HTML. The latest version of these docs live at: - [github.com/juju/docs](https://github.com/juju/docs) -- [jujucharms.com/docs](http://jujucharms.com/docs) - Rendered docs, generated every 15 minutes. +- [docs.jujucharms.com](http://docs.jujucharms.com) - Rendered docs -For advice on contributing to the docs (please!), see +For advice on contributing to the docs see the [contributing.html](https://jujucharms.com/docs/contributing.html) page in this project. This has important information on style, the use of Markdown and other useful tips. ## Docs structure -For editing actual documentation, you will find the Markdown format source -files in the `src/en` directory. At some point we hope to offer multilingual -versions of the docs, whereupon these will live in similarly titled directories -(e.g. 'fr', 'de', etc.). - -There are two other files in the `src` directory: +For editing actual documentation, you will find the source files in the +`src/en` directory. -**navigation.tpl** - This is used to build the navigation for the website. You +`metada.yaml` - This is used to build the navigation for the website. You won't need to change this unless you are adding a new page (and even then, please ask about where it should go). -**base.tpl** - this is the HTML template local docs use. This is as far as -possible a simulation of how the docs appear online, but changes to this file -do not alter the online appearance of the docs. +The `build` directory is where local builds of the docs are made, and contains +some support files (CSS, JavaScript) and all the graphics used by the docs. If +you need to add graphics, add them here: `htmldocs/media`. -The `htmldocs` directory is where local builds of the docs are made, and -contains some support files (CSS, JavaScript) and all the graphics used by the -docs. If you need to add graphics, add them here (`htmldocs/media`). - -**NOTE!** Please don't _replace_ graphics unless you know what you are doing. -These image files are used by all versions of the docs, so usually you will want -to add files rather than change existing ones, unless the changes apply to all -versions of Juju (e.g. website images). - -The `tools` directory is reserved for build tools and support files. +Do not _replace_ graphics unless you know what you are doing. These image files +are used by all versions of the docs, so usually you will want to add files +rather than change existing ones, unless the changes apply to all versions of +Juju (e.g. website images). The `versions` file contains a list of Github branches which represent the current supported versions of documentation. Many tools rely on this list, it should not be changed by anyone but the docs team! -The `archive` file contains a list of Github branches which contain unmaintained, -older versions of documentation. +The `archive` file contains a list of Github branches which contain +unmaintained, older versions of documentation. + +## Building the Docs + +Every non-trivial contribution must first have its HTML built and verified +before a pull request (PR) is made from it. + +See the [documentation-builder project][github-documentation-builder] for +details of the actual tool. + +### Installation + +Install the builder. On Ubuntu 16.04 LTS (or greater): + +```bash +sudo snap install documentation-builder +``` + +!!! Note: + You will first need to install package `squashfuse` if you're doing this in + a LXD container. + +### Build + +To build the HTML, while in the root of the docs repository: + +```bash +documentation-builder --source-folder src --media-path src/en/media +``` + +### Verification + +You can point a web browser at individual HTML files but to make your +verification more conclusive you will need a web server. + +#### Web server -The `Makefile` is used to build local versions of the docs, and other useful -things. Some of the make targets are: - - - **sysdeps** Run this first! It makes sure you have the required packages to - build the docs. - - **build** Uses the `tools/mdtool.py` program to build a local version of the - docs in the htmldocs directory - - **clean** Removes temp files and generated docs - - **serve** Runs a simple Python HTTP server on port 8000, which points at the - htmldocs directory - essential for testing! - - **todo** Scans the source files for metadata 'TODO' items, and dumps them in a - file called 'TODO.txt' +See the [Ubuntu Server Guide][ubuntu-serverguide-apache] for instructions on +setting up Apache. The DocumentRoot should be the `src/build/en` directory. To +test, point your browser at: +```no-highlight +http://127.0.0.1/ +``` +Alternatively, you can use Python to start a simple HTTP server (port 8000). +While in the `src/build/en` directory run: -## Typical Github workflow +```bash +python3 -m http.server +``` -Github, and git, allow you to use many different styles of workflow, but it is -tricky to get your head around initially, so here is an example of how to use it -easily for our documentation. +To test, point your browser at: -1. Make sure you have a Github account! [https://github.com/join](https://github.com/join) +```no-highlight +http://0.0.0.0:8000/ +``` + +#### Points to consider + +Some things to consider during verification: + + - A linkchecker (either a system-wide tool or a + [browser add-on][browser-linkchecker-addon]) + - Images should show enough context (surrounding real estate) but not so much + to make important details illegible. + +## Workflow + +1. Get a Github account: [https://github.com/join](https://github.com/join) 2. Fork the [juju/docs](https://github.com/juju/docs) Github repository. This creates your own version of the repository (which you can then find online at `https://github.com/{yourusername}/docs`) @@ -112,14 +144,13 @@ easily for our documentation. If you wish to move or rename files you need to use the `git mv` command, and the `git rm` command to delete them - 7. To 'save' your changes locally, you should make a commit: git commit -m 'my commit message which says something useful' -7. Check that the changes you have made make sense! You can build a local - version of the docs (` make && make serve`) to check it renders - properly. +7. View your changes to make sure they render properly. See previous section + [Building the docs][#building-the-docs] for how to build a local version of + the docs. 8. Push the branch back to **your** fork on Github @@ -133,25 +164,22 @@ easily for our documentation. - caching your [password] (https://help.github.com/articles/caching-your-github-password-in-git/) 9. Create a pull request. This is easily done in the web interface of Github: - navigate to your branch on the web interface and hit the compare button - - this will allow you to compare across forks to the juju/docs master branch, - which is where your changes will hopefully end up. The comparison will show - you a diff of the changes - it is useful to look over this to avoid - mistakes. Then click on the button to Create a pull request. - Add any useful info about the changes in the comments (e.g. if it fixes an - issue you can refer to it by number to automatically link your pull request - to the issue) + navigate to your branch on the web interface and hit the compare button - + this will allow you to compare across forks to the juju/docs master branch, + which is where your changes will hopefully end up. The comparison will show + you a diff of the changes - it is useful to look over this to avoid + mistakes. Then click on the button to Create a pull request. Add any useful + info about the changes in the comments (e.g. if it fixes an issue you can + refer to it by number to automatically link your pull request to the issue) 10. Wait. The documentation team will usually get to your pull request within a - day or two. Be prepared for suggested changes and comments. If there are - changes to be made: + day or two. Be prepared for suggested changes and comments. If there are + changes to be made: - make the changes in your local branch - use `git commit -m 'some message' ` to commit the new changes - push the branch to your fork again with `git push origin {branchname}` - there is no need to update the pull request, it will be updated automatically - - Once the code has been landed you can remove your feature branch from both the remote and your local fork. Github provides a button for this at the bottom of @@ -160,16 +188,15 @@ the pull request, or you can use `git` to remove the branch. Before creating another feature branch, make sure you update your fork's code by pulling from the original Juju repository (see below). - ## Keeping your fork in sync with Juju docs upstream You should now have both the upstream branch and your fork listed in git, `git remote -v` should return something like: upstream https://github.com/juju/docs.git (fetch) - upstream https://github.com/juju/docs.git (push) - origin https://github.com/castrojo/docs (fetch) - origin https://github.com/castrojo/docs (push) + upstream https://github.com/juju/docs.git (push) + origin https://github.com/your-github-id/docs (fetch) + origin https://github.com/your-github-id/docs (push) To fetch and merge with the upstream branch: @@ -179,39 +206,9 @@ To fetch and merge with the upstream branch: git push origin master + -## Additional resources - -### Tools - - -[Git Remote Branch](https://github.com/webmat/git_remote_branch>) - A tool to -simplify working with remote branches (Detailed installation instructions are -in their README). - - -### Using git aliases - -Git provides a mechanism for creating aliases for complex or multi-step -commands. These are located in your ``.gitconfig`` file under the -``[alias]`` section. - -If you would like more details on Git aliases, You can find out more -information here: [How to add Git aliases](https://git.wiki.kernel.org/index.php/Aliases>) - -Below are a few helpful aliases that have been suggested: - - - # Bring down the pull request number from the remote specified. - # Note, the remote that the pull request is merging into may not be your - # origin (your github fork). - fetch-pr = "!f() { git fetch $1 refs/pull/$2/head:refs/remotes/pr/$2; }; f" - - # Make a branch that merges a pull request into the most recent version of the - # trunk (the "juju" remote's develop branch). To do this, it also updates your - # local develop branch with the newest code from trunk. - # In the example below, "juju" is the name of your remote, "6" is the pull - # request number, and "qa-sticky-headers" is whatever branch name you want - # for the pull request. - # git qa-pr juju 6 qa-sticky-headers - qa-pr = "!sh -c 'git checkout develop; git pull $0 develop; git checkout -b $2; git fetch-pr $0 $1; git merge pr/$1'" +[#building-the-docs]: #building-the-docs +[github-documentation-builder]: https://github.com/CanonicalLtd/documentation-builder +[ubuntu-serverguide-apache]: https://help.ubuntu.com/lts/serverguide/httpd.html +[browser-linkchecker-addon]: https://chrome.google.com/webstore/detail/check-my-links/ojkcdipcgfaekbeaelaapakgnjflfglf From 380f0de3aac999ae4419ec5e18f91700f66a0a5b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 26 Oct 2018 16:11:47 -0400 Subject: [PATCH 096/311] trivial --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 182b86da6..f7026da1c 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ other useful tips. For editing actual documentation, you will find the source files in the `src/en` directory. -`metada.yaml` - This is used to build the navigation for the website. You +`metadata.yaml` - This is used to build the navigation for the website. You won't need to change this unless you are adding a new page (and even then, please ask about where it should go). From ed9d74a9076ee2d34165ed17ca95f28f709a468a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 30 Oct 2018 21:58:03 -0400 Subject: [PATCH 097/311] start --- src/en/contributing.md | 376 ++++++++++++++++++++++++++++------------- 1 file changed, 256 insertions(+), 120 deletions(-) diff --git a/src/en/contributing.md b/src/en/contributing.md index 964397cf8..ab9ec5130 100644 --- a/src/en/contributing.md +++ b/src/en/contributing.md @@ -1,197 +1,333 @@ -Title: Contributing to Juju docs +Title: Writing Guide +table_of_contents: True -# Contributing to Juju documentation +# Writing Guide -Juju documentation is hosted on [GitHub](http://github.com) and published on -[jujucharms.com](http://jujucharms.com/docs). Its source documents are easy to -understand and edit due to the format used: standard -[GitHub Flavored Markdown](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github/). -Conventions have been added to support doc features such as *foldouts* and -*admonishments* (explained below). +This page contains detailed information on how to become a successful Juju +documentation writer. Welcome to the club. -Here are a few [cheat](http://askubuntu.com/editing-help) -[sheets](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for -writing in GFM. +## Contribution overview +An individual doc contribution ends up as a *PR* (pull request) on GitHub. The +process involved in producing one is described on the project +[README][juju-docs-readme] page. -## Documentation bugs +Prior to submitting a PR the contributor must verify that the HTML is good. +The README also covers this. -Bugs for documentation issues are submitted here: +A Documentation team member will review your PR, suggest improvements, and +eventually merge it with the appropriate branch (series). Publication to the +website is a separate step (performed internally), so it can be a few days +before the changes actually show up. Please be patient! -https://github.com/juju/docs/issues/new +## Style and language -and listed here: +Please follow these guidelines for style and language: -https://github.com/juju/docs/issues + - Use a spell checker. + - Resist being overly formal. + - Verify hyperlinks and examples. + - Target audience: intermediate system administrator, not a developer. + - Use British English (en-GB). See [language details][contributing-en-gb], + including a comparison with American English (en-US). + - Use a maximum of 79 columns for files. Here are instructions for the + [vim][vim-eighty-columns] editor. + - An exception to the above is a hyperlink. Never break one with a carriage + return. This includes the `[text][label]` and `[label]: destination` + combinations. See [hyperlinks][anchor__hyperlinks]. +## GitHub Flavored Markdown -## How to contribute text +This documentation is written in GitHub Flavored Markdown. GFM conventions +have been added to support features such as [foldouts][anchor__foldouts] and +[admonishments][anchor__admonishments]. -Here are the basic steps necessary to get a change published on the website: +GFM is very easy to write with. Get started by looking over the below +resources: -- [Fork the repository](https://help.github.com/articles/fork-a-repo) from [github.com/juju/docs](http://github.com/juju/docs) -- Make a local branch from your fork (and enter that branch) -- Edit the source documents -- Push your branch back to your fork on GitHub -- [Submit a Pull Request](https://help.github.com/articles/creating-a-pull-request) + - [askubuntu.com][gfm-cheatsheet-askubuntu] + - [github.com][gfm-cheatsheet-github] -The source documents are located in the `src` directory. From there each -language is separated into its own directory by language code. For instance, -English is under `src/en`. +## Metadata -Once submitted, a Docs team member will review your work, suggest improvements, -and eventually merge it with the master branch. Don't forget to review your -work before submission! +Metadata can be included in any file. Currently, this is used for: + - title element + - TODO list (file improvements) + - table of contents -### Metadata +This information is written as key:value pairs at the very top of the page. For +example: -Each file has the potential to include metadata for various purposes. At the -moment this is used to provide a title element, and also to implement a limited -form of todo list items. Metadata is written as _key : value_ pairs AT THE VERY -TOP of the document. E.g. - -``` -Title: Contributing to Juju docs -TODO: add section on metadata - spellcheck everything +```no-highlight +Title: Install from ISO +TODO: images need updating when Ubuntu 17.04 is released + check for changes to bug https://pad.lv/1625211 and modify text accordingly +table_of_contents: True # Title of document -Well written text goes here blah blah +Text goes here blah blah blah ``` -As you can see, the TODO metadata can have more than one item, as long as -additional items are indented by at least 4 spaces directly after the previous -one. The Metadata section ends immediately there is a blank line, and the -normal document text can begin. +- The TODO items must be left-aligned as shown above. +- The table of contents will contain only level 2 headers. +- The metadata section is terminated by a blank line. +## Headers -### Sections +Headers are simple to create: -All the text is organised into sections. These are auto-generated, there is -nothing extra you need to do: + # Top level header (typically the same as the Title element) + ## Second level header + ### Third level header - #

equivalent - ##

equivalent - ###

equivalent +## Code blocks +A code block is enclosed by three backticks and includes the *type* of code: -### Code blocks + ```bash + juju command do something + juju command do something else + ``` -Create a code block using the code-fencing markup of three backticks, -preferably followed by the type of code: +The most common types used are: `bash`, `yaml`, `json`, and `no-highlight`. +The last is like a miscellaneous type. It is often used to display command +output. - ```bash - juju do something - juju status - ``` +## Inline code -The most common "types" used in this documentation are: `bash`, `yaml`, `json`, -and `no-highlight`. +Use a backtick to inline commands and other literals. For instance, to get +this: +A controller is created with the `bootstrap` command. -### Inline code +you would write this: -Use a backtick to `inline commands and other literals`: +```no-highlight +A controller is created with the `bootstrap` command. +``` +## Admonishments + +An admonishment distinguishes information from the rest of the text. The syntax +begins with 3 exclamation points: + +```no-highlight +!!! [admonishment-type] "[title]": + [aligned text] +``` -### Notes, warnings, callouts, and admonishments +Where: -Callouts are used to notify the user of additional information or warn them of -potential pitfalls. This will create a notification resembling the following in -the docs: +- `admonishment-type` can be 'Note', 'Warning', 'Positive', or 'Negative'. +- `title` is an optional title (visible in HTML) +- `aligned text` is the text -![callout](media/note.png) +When a value for 'title' is omitted, the default will be the type itself. If +the 'title' has a null value (i.e. "") then no title will be displayed. -To implement this callout, use the following syntax: +### Admonishment examples + +A standard 'Note' type admonishment: ```no-highlight !!! Note: - If you want to get more information on what is actually happening, or - to help resolve problems, you can add the `--show-log` switch to the juju - command to get verbose output. + If KVM-backed nodes are used, ensure that the 'maas' user on the rack + controller can connect to the KVM host using a passphraseless private SSH + key. +``` + +A standard 'Warning' type admonishment: + +```no-highlight +!!! Warning: + Data will be lost unless you do the right thing. ``` +A 'Positive' type admonishment with title: -### Foldouts +```no-highlight +!!! Positive "High score": + A positive note that should include a title. +``` -When a page contains a high volume of information that would otherwise require -a table of contents, or similar method of quick navigation, a *foldout* can be -used. This will create a collapsed header which, when clicked, will expand to -display all the content below it. +A 'Negative' type admonishment with title: +```no-highlight +!!! Negative "Game over": + A negative note that should include a title. +``` + +A 'Positive' type admonishment with no title: + +```no-highlight +!!! Positive "": + I'm done, and I feel fine. +``` + +The above examples will appear as: + +!!! Note: + If KVM-backed nodes are used, ensure that the 'maas' user on the rack + controller can connect to the KVM host using a passphraseless private SSH + key. + +!!! Warning: + Data will be lost unless you do the right thing. + +!!! Positive "High score": + A positive note that should include a title. + +!!! Negative "Game over": + A negative note that should include a title. + +!!! Positive "": + I'm done, and I feel fine. + +## Comments + +Occasionally it may be appropriate to include a comment to explain or organize +some text. This ends up as an HTML comment which can be read online so take it +seriously: + +```no-highlight + ``` + +## Foldouts + +When a page contains a lot of extraneous information such as walkthroughs +containing many images or reference tables, a *foldout* can be used. This will +create a collapsed header which, when clicked, will expand to display all the +content below it. + +```no-highlight ^# Header Content can be multi-paragraphed and will be sent through the Markdown parser as long as content is continually indented under the header. ``` +## Hyperlinks -## Adding pages +Links to internal files or external URLs use the following format: -Adding a page (file) to the documentation requires the altering of -`src/navigation.tpl`. Doing so will insert an entry into the left navigation -pane which will allow a visitor to discover the new page. +```no-highlight +[visible text][label] +``` -Add the page with the following format: +The `visible text` is what will appear on the web page. The `label` is used to +refer to the destination, which is placed at the bottom of the file: -
  • Scaling Services
    • ; +``` + -in the appropriate section. Please make sure you submit a Pull Request with a -description of the new page and why it is needed! +[label]: destination +``` +For example: -## Adding screenshots +```no-highlight +- For more on this topic see [DHCP][dhcp]. +- To understand haproxy, see the [upstream configuration manual][upstream-haproxy-manual]. -When adding screenshots place them in `htmldocs/media`. To reference them in -your page use the syntax `![description](media/picture.png)` +... +[dhcp]: installconfig-networking-dhcp.md +[upstream-haproxy-manual]: http://cbonte.github.io/haproxy-dconv/1.6/configuration.html +``` -# Testing or deploying locally +The visible text should use an active style as opposed to a passive style. For +instance, try to avoid: -First you need to generate the docs from the Markdown. In the root directory -first get the dependencies and make the docs: +```no-highlight +A [proxy][maas-proxy] can optionally be configured. +``` - make sysdeps - make +Notes: -!!! Note: - You only need to `make sysdeps` once, after that you'll have all the - dependencies you'll need to build the docs going forward. +- An internal page is referred to by its source filename (i.e. `.md` not + `.html`). +- Try to use the same `label:destination` pair throughout the documentation. + +## Images + +An image should not be overly cropped - allow for context. When ready, place +the image file in the `media` directory. + +In terms of linking, they are managed very similarly to hyperlinks. However, +they are placed on their own line; are preceded by an exclamation point; and +both the label and destination have a specific naming convention: + +```no-highlight +![alt attribute][img__webui_descriptor] +``` + +The bottom of the file will look like: + +```no-highlight +[img__webui_descriptor]: ../media/filename__webui_descriptor.png +``` + +Explanation: + +- `filename`: name of file containing the image (omit the extension '.md') +- `webui`: version of the Juju GUI corresponding to the image of the web UI +- `alt attribute`: text that is shown in place of the image if the latter + cannot be displayed for some reason +- `descriptor`: a short description of the image (e.g. 'enable-dhcp') + +For example: + +```no-highlight +![enable dhcp][img__2.1_enable-dhcp] +![enable fire alarm][img__enable-fire-alarm] + +... + +[img__2.1_enable-dhcp]: ../media/installconfig-networking-dhcp__2.1_enable-dhcp.png +[img__enable-fire-alarm]: ../media/installconfig-networking-dhcp__enable-fire-alarm.png +``` + +If the image is not of the Juju web UI then simply omit the version part, like +in the second image above. + +### Central images directory -The documentation makes use of Javascript for some functionality, so in order -to test the docs properly you will need to have a web server set up. See -[Ubuntu and Apache](https://help.ubuntu.com/lts/serverguide/httpd.html). The -DocumentRoot should be the `htmldocs` directory: +For publication (on the web site), all branch series use the `htmldocs/media` +directory in the 'master' branch. This means: - sudo cp -R htmldocs /var/www/htmldocs +- You must be very careful when renaming or removing an image in master as it + will affect all non-master branches. +- Any image introduced in a non-master branch must be *forward-ported* to the + master branch. -You can then point your web browser at your local machine (127.0.0.1/htmldocs) -to view the files. +## Capitalization -Alternatively, you can use Python to start a simple HTTP server on the docs -directory. Navigate to the `/htmldocs` directory of the docs and run the -following: +Do not use a "Caps Everywhere" style. It is only used in level one headers and +the title metadata. References (visible text) to these page titles (including +the navigation) should just capitalize the first letter. Obviously, this does +not pertain to words that should always be capitalized according to basic +grammar rules (e.g. acronyms, proper nouns). - python -m SimpleHTTPServer +## Navigation menu +Adding a page (file) to the documentation may require the altering of +`src/en/metadata.yaml`. Doing so will insert an entry into the left navigation +pane (the menu) on the website. This is considered a major change so ensure +your PR includes a comment highlighting this change and why it is needed. -# Style and language + -We are putting together a more comprehensive style guide, but for the moment the -following are good guidelines: +[anchor__hyperlinks]: #hyperlinks +[anchor__foldouts]: #foldouts +[anchor__admonishments]: #admonishments - - Resist being overly formal. The documentation should be like having a - conversation with a knowledgeable friend - - Remember the readers are *users* not necessarily Juju developers - - Spell things properly! (see below) - - We use British English (en-GB). See - [language details](./contributing-en-GB.html), including a comparison with - American English (en-US). - - If including links or examples, double-check they actually work - - We enforce 80 columns for every text file to keep it readable. Here are - instructions for the - [vim](http://stackoverflow.com/questions/3033423/vim-command-to-restructure-force-text-to-80-columns) - and [emacs](http://www.emacswiki.org/emacs/EightyColumnRule) editors. +[juju-docs-readme]: +[gfm-cheatsheet-askubuntu]: http://askubuntu.com/editing-help +[gfm-cheatsheet-github]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet +[contributing-en-gb]: contributing-en-GB.md +[vim-eighty-columns]: http://stackoverflow.com/questions/3033423/vim-command-to-restructure-force-text-to-80-columns From c907b82c4fb1e0e1f5fc89184222d109fd6698b8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 31 Oct 2018 09:08:57 -0400 Subject: [PATCH 098/311] update contributing.md --- README.md | 65 +++++++++++++++++++++--------------------- src/en/contributing.md | 23 +++++---------- 2 files changed, 40 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index f7026da1c..1b2b40e31 100644 --- a/README.md +++ b/README.md @@ -15,37 +15,36 @@ The latest version of these docs live at: - [github.com/juju/docs](https://github.com/juju/docs) - [docs.jujucharms.com](http://docs.jujucharms.com) - Rendered docs -For advice on contributing to the docs see -the [contributing.html](https://jujucharms.com/docs/contributing.html) page in -this project. This has important information on style, the use of Markdown and -other useful tips. +For advice on contributing to the docs see the +[contributing.html](https://docs.jujucharms.com/stable/contributing.html) page +in this project. This has important information on style, the use of Markdown +and other useful tips. -## Docs structure +## Important files and directories -For editing actual documentation, you will find the source files in the -`src/en` directory. +The following files and directories under `src/en` are of interest: -`metadata.yaml` - This is used to build the navigation for the website. You -won't need to change this unless you are adding a new page (and even then, -please ask about where it should go). + - The `metadata.yaml` file is used to build the navigation for the website. + You won't need to change this unless you are adding a new page (and even + then, please ask about where it should go). -The `build` directory is where local builds of the docs are made, and contains -some support files (CSS, JavaScript) and all the graphics used by the docs. If -you need to add graphics, add them here: `htmldocs/media`. + - The `build` directory is where local builds of the docs are made, and + contains some support files (CSS, JavaScript) and all the graphics used by + the docs. If you need to add graphics, add them here: `htmldocs/media`. -Do not _replace_ graphics unless you know what you are doing. These image files -are used by all versions of the docs, so usually you will want to add files -rather than change existing ones, unless the changes apply to all versions of -Juju (e.g. website images). + Do not _replace_ graphics unless you know what you are doing. These image + files are used by all versions of the docs, so usually you will want to add + files rather than change existing ones, unless the changes apply to all + versions of Juju (e.g. website images). -The `versions` file contains a list of Github branches which represent the -current supported versions of documentation. Many tools rely on this list, it -should not be changed by anyone but the docs team! + - The `versions` file contains a list of Github branches which represent the + current supported versions of documentation. Many tools rely on this list, + it should not be changed by anyone but the docs team! -The `archive` file contains a list of Github branches which contain -unmaintained, older versions of documentation. + - The `archive` file contains a list of Github branches which contain + unmaintained, older versions of documentation. -## Building the Docs +## Building the documentation Every non-trivial contribution must first have its HTML built and verified before a pull request (PR) is made from it. @@ -78,8 +77,6 @@ documentation-builder --source-folder src --media-path src/en/media You can point a web browser at individual HTML files but to make your verification more conclusive you will need a web server. -#### Web server - See the [Ubuntu Server Guide][ubuntu-serverguide-apache] for instructions on setting up Apache. The DocumentRoot should be the `src/build/en` directory. To test, point your browser at: @@ -172,14 +169,18 @@ Some things to consider during verification: info about the changes in the comments (e.g. if it fixes an issue you can refer to it by number to automatically link your pull request to the issue) -10. Wait. The documentation team will usually get to your pull request within a - day or two. Be prepared for suggested changes and comments. If there are - changes to be made: +10. A Documentation team member will review your PR, suggest improvements, and + eventually merge it with the appropriate branch (series). Publication to + the website is a separate step (performed internally), so it can be a few + days before the changes actually show up. + + If there are changes to be made: - - make the changes in your local branch - - use `git commit -m 'some message' ` to commit the new changes - - push the branch to your fork again with `git push origin {branchname}` - - there is no need to update the pull request, it will be updated automatically + - make the changes in your local branch + - use `git commit -m 'some message' ` to commit the new changes + - push the branch to your fork again with `git push origin {branchname}` + - there is no need to update the pull request, it will be done + automatically Once the code has been landed you can remove your feature branch from both the remote and your local fork. Github provides a button for this at the bottom of diff --git a/src/en/contributing.md b/src/en/contributing.md index ab9ec5130..cbd117ee2 100644 --- a/src/en/contributing.md +++ b/src/en/contributing.md @@ -6,20 +6,10 @@ table_of_contents: True This page contains detailed information on how to become a successful Juju documentation writer. Welcome to the club. -## Contribution overview - An individual doc contribution ends up as a *PR* (pull request) on GitHub. The process involved in producing one is described on the project [README][juju-docs-readme] page. -Prior to submitting a PR the contributor must verify that the HTML is good. -The README also covers this. - -A Documentation team member will review your PR, suggest improvements, and -eventually merge it with the appropriate branch (series). Publication to the -website is a separate step (performed internally), so it can be a few days -before the changes actually show up. Please be patient! - ## Style and language Please follow these guidelines for style and language: @@ -34,13 +24,13 @@ Please follow these guidelines for style and language: [vim][vim-eighty-columns] editor. - An exception to the above is a hyperlink. Never break one with a carriage return. This includes the `[text][label]` and `[label]: destination` - combinations. See [hyperlinks][anchor__hyperlinks]. + combinations. See [hyperlinks][#hyperlinks]. ## GitHub Flavored Markdown This documentation is written in GitHub Flavored Markdown. GFM conventions -have been added to support features such as [foldouts][anchor__foldouts] and -[admonishments][anchor__admonishments]. +have been added to support features such as [foldouts][#foldouts] and +[admonishments][#admonishments]. GFM is very easy to write with. Get started by looking over the below resources: @@ -322,9 +312,10 @@ your PR includes a comment highlighting this change and why it is needed. -[anchor__hyperlinks]: #hyperlinks -[anchor__foldouts]: #foldouts -[anchor__admonishments]: #admonishments +[juju-docs-readme]: https://github.com/juju/docs/blob/master/README.md +[#hyperlinks]: #hyperlinks +[#foldouts]: #foldouts +[#admonishments]: #admonishments [juju-docs-readme]: [gfm-cheatsheet-askubuntu]: http://askubuntu.com/editing-help From 051f29f10e217c6e7b21847a2ac4b3902679863d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 31 Oct 2018 10:06:54 -0400 Subject: [PATCH 099/311] trivial --- src/en/contributing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/en/contributing.md b/src/en/contributing.md index cbd117ee2..0acd4667b 100644 --- a/src/en/contributing.md +++ b/src/en/contributing.md @@ -1,7 +1,7 @@ -Title: Writing Guide +Title: Writing guide table_of_contents: True -# Writing Guide +# Writing guide This page contains detailed information on how to become a successful Juju documentation writer. Welcome to the club. @@ -310,14 +310,14 @@ Adding a page (file) to the documentation may require the altering of pane (the menu) on the website. This is considered a major change so ensure your PR includes a comment highlighting this change and why it is needed. + -[juju-docs-readme]: https://github.com/juju/docs/blob/master/README.md [#hyperlinks]: #hyperlinks [#foldouts]: #foldouts [#admonishments]: #admonishments -[juju-docs-readme]: +[juju-docs-readme]: https://github.com/juju/docs/blob/master/README.md [gfm-cheatsheet-askubuntu]: http://askubuntu.com/editing-help [gfm-cheatsheet-github]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet [contributing-en-gb]: contributing-en-GB.md From 07f10c565e7d366350d1c083e4117b737ebc6abb Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 31 Oct 2018 10:36:24 -0400 Subject: [PATCH 100/311] remove file --- src/en/tools-mojo.md | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 src/en/tools-mojo.md diff --git a/src/en/tools-mojo.md b/src/en/tools-mojo.md deleted file mode 100644 index 742645e98..000000000 --- a/src/en/tools-mojo.md +++ /dev/null @@ -1,19 +0,0 @@ -Title: Mojo - -# Mojo - -The Mojo package provides tools to install, configure, and verify Juju-based -deployments. It is being applied successfully for the purpose of continuous -integration (CI) at the enterprise level. - -Mojo is an open source project available under the GPLv3 license and is hosted -on Launchpad. See the [Mojo project][mojo]. - -For documentation, visit the upstream site at -[https://mojo.canonical.com][upstream-mojo-url]. - - - - -[mojo]: https://launchpad.net/mojo -[upstream-mojo-url]: https://mojo.canonical.com From 1d86f7ae2cffb9b3c34c2c6faea54ea318428b52 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 31 Oct 2018 10:44:29 -0400 Subject: [PATCH 101/311] trivial --- src/en/clouds.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/en/clouds.md b/src/en/clouds.md index 28a131c25..610534137 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -4,8 +4,6 @@ TODO: Bug tracking: https://bugs.launchpad.net/juju/+bug/1749302 INFO: Auth types found at ~/.local/share/juju/public-clouds.yaml There is contention whether access-key can be used with keystone v3 (see https://github.com/juju/docs/issues/2868) Needs to be updated for the new Oracle cloud (OCI) - Update: Juju is growing an authentication type for OpenStack: certificates - Update: Juju is growing add-cloud for (remote) LXD table_of_contents: True # Clouds @@ -19,11 +17,11 @@ shown, it is simply done. They are VMware vSphere, OpenStack, MAAS, and Manual. An Oracle *trial* account also needs to be added. Once your cloud is known to Juju, whether by default or due to it being added, -the next step is to add your cloud credentials to Juju. The exception is LXD; -it does not require credentials. +the next step is to add your cloud credentials to Juju. The exception is for a +local LXD cloud; credentials are added automatically. -This rest of this page covers general cloud management tasks and an overview of -how clouds are added. You can still get started by selecting your cloud here: +This rest of this page covers general cloud management and an overview of how +clouds are added. You can still get started by selecting your cloud here: - [Amazon AWS][clouds-aws] - [Microsoft Azure][clouds-azure] @@ -39,7 +37,8 @@ how clouds are added. You can still get started by selecting your cloud here: ## General cloud management -To see which clouds Juju is currently aware of use the `clouds` command: +To get the list of clouds that Juju is currently aware of use the `clouds` +command: ```bash juju clouds From 116a05d1da5d7e50e5a63abce3b9cd24cea15383 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 31 Oct 2018 16:25:56 -0400 Subject: [PATCH 102/311] improvements --- src/en/credentials.md | 66 +++++++++++++++++++++++++------------------ 1 file changed, 38 insertions(+), 28 deletions(-) diff --git a/src/en/credentials.md b/src/en/credentials.md index ca38d5842..cbf022dda 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -8,20 +8,21 @@ table_of_contents: True # Credentials In order to access your cloud, Juju needs to know how to authenticate itself. -We use the term *credentials* to describe the material necessary to do this -(e.g. username & password, or just a secret key). Such a set of credentials is -represented by a *credential name* that is used to refer to those credentials -in subsequent commands. +We use the term *credential* to collectively describe the material necessary to +do this (e.g. username & password, or just a secret key). During the addition +of a credential the user assigns to it an arbitrary name. -When credentials are added for a given cloud they become available to use on +When credentials are added for a given cloud they become available for use on that cloud's controller and models. There are therefore two categories of credentials: those that are available to the Juju client (local) and those that -are active and have been uploaded to a controller (remote). A credential -becomes active when it is needed to bring about a change in Juju for the first -time. +are active and have been uploaded to a controller (remote). + +A credential becomes active when it is related to a model for the first time. +The two commands that can do this are `bootstrap` and `add-model` as both +commands involve the creation of at least one model. An active credential is always associated with one cloud, one Juju user, and -one, or more, models. A model, however, is always linked to a single +one, or more, models. A model, however, is always related to a single credential. ## Adding credentials @@ -235,14 +236,14 @@ juju set-default-credential aws carol If only one credential exists for a cloud, it becomes the effective default credential for that cloud. -Setting a default affects operations that require a credential such as creating -a controller (`bootstrap`) and adding a model (`add-model`). It does not change -what is currently in use (on a controller). With both these commands a -credential can be specified with the `--credential` option. +Setting a default affects operations that require a new credential to be used +by Juju. These are the creation of a controller (`bootstrap`) and the addition +of a model (`add-model`). It does not change what is currently in use (on a +controller). -A default must be defined if multiple credentials exist for a given cloud. -Failure to do so will cause an error to be emitted from those commands that -require a credential: +A default must be defined if multiple credentials exist for a given cloud. With +both the above commands a credential can be specified with the `--credential` +option. Failure to do so will cause an error to be emitted: ```no-highlight ERROR more than one credential is available @@ -353,7 +354,7 @@ the `--replace` option. Here we decided to use the file 'mycreds.yaml' from a previous example: ```bash -juju add-credential aws -f mycreds.yaml --replace +juju add-credential --replace aws -f mycreds.yaml ``` Any existing credential will be overwritten by an identically named credential @@ -365,30 +366,35 @@ ERROR local credentials for cloud "aws" already exist; use --replace to overwrit ``` Updating credentials in this way does not update credentials currently in use -(on an existing controller/cloud). See the next section for that. The -`add-credential` command is always "pre-bootstrap" in nature. +(on an existing controller/cloud). See the next section for that. ### Updating remote credentials -To update credentials currently in use (i.e. cached on the controller) the -`update-credential` command is used. The requirements for using this command, -as compared to the initial `juju bootstrap` (or `juju add-model`) command, are: +To update credentials currently in use (i.e. stored on a controller) the +`update-credential` command is used. It does this by uploading an identically +named local credential. + +Before an update occurs, Juju ensures that the new credential contents can +authenticate with the backing cloud and that any machines that may reside +within a model currently related to the credential remain accessible. + +The requirements for using this command, as compared to the initial `bootstrap` +(or `juju add-model`) command, are: - same cloud name - same Juju username (logged in) - same credential name -The update is a two-step process. First change the credentials locally with the -`add-credential` command (in conjunction with the `--replace` option) and then -upload those credentials to the controller. +The update is a two-step process. First change the credentials locally as shown +previously and then upload those credentials to the controller. Below, we explicitly log in with the correct Juju username ('admin'), change -the contents of the credential called 'joe', and then update them on a Google -cloud controller: +the contents of the credential called 'joe' (included in file `mycreds.yaml`), +and then update that credential for cloud 'google': ```bash juju login -u admin -juju add-credential --replace joe +juju add-credential --replace google -f mycreds.yaml juju update-credential google joe ``` @@ -458,6 +464,10 @@ cloud 'aws'): juju set-credential -m trinity aws bob ``` +This command does not affect how the credential may relate to another model. If +the credential is already related to a single model this operation will result +in that credential being related to two models. + !!! Note: If the stated credential does not exist remotely but it does locally then the local credential will be uploaded to the controller. The command will From 8dcb7ded0212f7785576999df730b7ec6fd7eb3a Mon Sep 17 00:00:00 2001 From: Casey Marshall Date: Wed, 31 Oct 2018 17:00:08 +0000 Subject: [PATCH 103/311] SLA and budgeting documentation for Juju experts. --- src/en/experts-sla.md | 149 ++++++++++++++++++++++++++++++++++++++++++ src/en/metadata.yaml | 6 ++ 2 files changed, 155 insertions(+) create mode 100644 src/en/experts-sla.md diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md new file mode 100644 index 000000000..47d87366d --- /dev/null +++ b/src/en/experts-sla.md @@ -0,0 +1,149 @@ +Title: Managed solutions under SLA + +# Managed solutions under SLA + +[Juju experts](https://jujucharms.com/experts) may designate a Juju +model as a managed, supported solution by setting an SLA. + +There are three support levels that may be set on a model: + +- Essential +- Standard +- Advanced + +Our Juju expert partners support the managed solution itself, including its +workloads and operation. Support for Juju and Ubuntu is provided by +Canonical. See [Ubuntu Advantage for Servers](https://www.ubuntu.com/support/plans-and-pricing#server) +for more information on Canonical support levels. + +Juju experts will provide details on the solution-specific support provided +under each SLA, with budget estimates. + +## Setting an SLA on a model + +An SLA is set on a model with a monthly budget limit. Support costs will not be +billed for more than this amount. If metered costs exceed this amount, the +budget limit will need to be increased in order to continue to access support. + +Set an Essential SLA on the current model _marketdata_, with a monthly budget +limit of $100 USD: + +```bash +juju sla essential --budget 100 +``` + +``` +Model SLA Message +jaas:bob/marketdata essential the new sla will become effective on 2018-10-31 + 16:24:53.80664498 +0000 UTC +``` + +An SLA may be increased (from _essential_ to _standard_, or _standard_ to +_advanced_) effective immediately. Lowering the SLA becomes effective in the +next monthly billing cycle. + +The SLA for a model is shown at the top of Juju status. + +```bash +juju status +``` + +``` +Model Controller Cloud/Region Version SLA Timestamp +marketdata jaas azure/westeurope 2.4.3 essential 11:21:41-05:00 +... +``` + +# Budgeting managed models + +SLA budgets are organized into wallets. The sum of all budgets in a wallet +cannot exceed the wallet limit. + +## Managing wallets + +List your wallets with: + +```bash +juju wallets +``` + +``` +Wallet Monthly Budgeted Available Spent +primary* 1000 100 1000.00 0.00 +Total 1000 100 1000.00 0.00 + +Credit limit: 10000 +``` + +The default wallet is shown with an asterisk "\*". SLA budgets are allocated +from this wallet if the wallet name is not specified. + +The credit limit is the maximum monthly limit approved to spend on SLAs. If you +need to increase this limit, you may [contact JAAS support](https://jujucharms.com/support/create) +to raise it. + +View the budgets allocated from a wallet: + +```bash +juju show-wallet primary +``` + +``` +Model Spent Budgeted By Usage +jaas:bob/marketing-campaign 0.00 100 bob 0% + +Total 0.00 100 0% +Wallet 1000 +Unallocated 900 +``` + +You may increase the budget limit for a model: + +```bash +juju budget -m demo-izae7oj5:admin/doctest-03 250 +``` + +``` +budget limit updated to 250 +``` + +```bash +juju show-wallet personal +``` + +``` +Model Spent Budgeted By Usage +jaas:bob/marketing-campaign 0.00 250 bob 0% + +Total 0.00 250 0% +Wallet 1000 +Unallocated 750 +``` + +The budget limit may be lowered, but not below the current spend. + +## Advanced budgeting + +You may create additional wallets for accounting or organizational purposes. + +```bash +juju create-wallet demo-poc 200 +wallet created +``` + +```bash +juju wallets +Wallet Monthly Budgeted Available Spent +demo-poc 200 0 200.00 0.00 +personal* 1000 100 1000.00 0.00 +Total 1200 100 1200.00 0.00 + +Credit limit: 10000 +``` + +To allocate a budget from a specific wallet, use _wallet_:_limit_ when setting +the budget on an SLA. + +```bash +juju sla essential demo-poc:50 +``` diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 1870ba5d1..99d28d67b 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -48,6 +48,12 @@ navigation: - title: Juju users location: users.md + - title: Juju Experts + + children: + - title: Managed solutions under SLA + location: experts-sla.md + - title: Advanced topics children: From 9755fcebd7d6428929880a6fc3a8e9cdd29a0a06 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 1 Nov 2018 11:07:37 -0400 Subject: [PATCH 104/311] move up scaling; rename users --- src/en/metadata.yaml | 6 +++--- src/en/users.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 1870ba5d1..f58324ef7 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -27,14 +27,14 @@ navigation: location: charms-config.md - title: Managing relations location: charms-relations.md + - title: Scaling applications + location: charms-scaling.md - title: Removing things location: charms-destroy.md - title: Administering Juju children: - - title: Scaling applications - location: charms-scaling.md - title: Upgrading applications location: charms-upgrading.md - title: Upgrading a machine series @@ -45,7 +45,7 @@ navigation: location: controllers-ha.md - title: Application high availability location: charms-ha.md - - title: Juju users + - title: Understanding users location: users.md - title: Advanced topics diff --git a/src/en/users.md b/src/en/users.md index fd2e96749..be15d081a 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -1,9 +1,9 @@ -Title: Juju and users +Title: Understanding users TODO: User abilities, especially owners and regular users Critical: review required -# Juju users +# Understanding users There are 3 kinds of Juju users: controller administrators, model owners, and regular users. Each user, no matter the kind, is associated with a controller. From 3e94274c4ebb7b2d8e9afe25b6d9a6a8ac22afda Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 1 Nov 2018 15:37:19 -0400 Subject: [PATCH 105/311] integrate expose page into deploying page --- src/en/charms-deploying.md | 74 +++++++++++++++++++++++++++++--------- src/en/charms-exposing.md | 71 ------------------------------------ src/en/metadata.yaml | 2 -- 3 files changed, 57 insertions(+), 90 deletions(-) delete mode 100644 src/en/charms-exposing.md diff --git a/src/en/charms-deploying.md b/src/en/charms-deploying.md index b0aa8b836..5470d7f1d 100644 --- a/src/en/charms-deploying.md +++ b/src/en/charms-deploying.md @@ -12,12 +12,18 @@ things. Charms can exist online (in the [Charm Store][charm-store]) or on your local filesystem (previously downloaded from the store or written locally). Charms use the concept of *series* analogous as to how Juju does with Ubuntu -series ('Trusty', 'Xenial', etc). For the most part, this is transparent as +series ('Xenial', 'Bionic', etc). For the most part, this is transparent as Juju will use the most relevant charm to ensure things "just work". The default series can be configured at a model level, see [Configuring models][models-config] for further details. In the absence of this setting, the default is to use the series specified by the charm. +Deploying a charm does not make its related application instantly accessible. +This is because most clouds enforce default network security policies that +prohibit incoming traffic. Thankfully, Juju can request that the necessary +changes be made. See section below entitled +[Exposing deployed applications][#exposing-deployed-applications]. + ## Deploying from the Charm Store Typically, applications are deployed using the online charms. This ensures that @@ -54,7 +60,7 @@ juju deploy mysql mysql1 ### Channels -The charm store offers charms in different stages of development. Such stages +The Charm Store offers charms in different stages of development. Such stages are called *channels*. Some users may want the very latest features, or be part of a beta test; others may want to only install the most reliable software. The channels are: @@ -86,17 +92,50 @@ approximates your choice if it is not available. See [Upgrading applications][charms-upgrading] for how charm upgrades work. +## Deploying from a local charm + +It is possible to deploy applications using local charms. See +[Deploying charms offline][charms-offline-deploying] for further guidance. + +## Exposing deployed applications + +Once an application is deployed changes need to be made to the backing cloud's +firewall to permit network traffic to contact the application. This is done +with the `expose` command. + +Assuming the 'wordpress' application has been deployed (and a relation has been +made to deployed database 'mariadb'), we would expose it in this way: + +```bash +juju expose wordpress +``` + +The below partial output from the `status` command informs us that the +'wordpress' application is currently exposed. In this case it is available via +its public address of 54.224.246.234: + +```no-highlight +App Version Status Scale Charm Store Rev OS Notes +mariadb 10.1.36 active 1 mariadb jujucharms 7 ubuntu +wordpress active 1 wordpress jujucharms 5 ubuntu exposed + +Unit Workload Agent Machine Public address Ports Message +mariadb/0* active idle 1 54.147.127.19 ready +wordpress/0* active idle 0 54.224.246.234 80/tcp +``` + +Use the `unexpose` command to undo the changes: + +```bash +juju unexpose wordpress +``` + ## Deploying a multi-series charm Some charms support more than one series. It is also possible to force a charm to deploy to a different series. See the documentation on [Multi-series charms][deploying-multi-series-charms] to learn more. -## Deploying from a local charm - -It is possible to deploy applications using local charms. See -[Deploying charms offline][charms-offline-deploying] for further guidance. - ## Configuring at deployment time Deployed applications usually start with a sane default configuration. However, @@ -131,7 +170,7 @@ applications at deployment time. See [Deploying to network spaces][deploying-to-network-spaces] for more information. -## Scaling out +## Scaling out deployed applications A common enterprise requirement, once applications have been running for a while, is the ability to scale out (and scale back) one's infrastructure. @@ -143,12 +182,13 @@ matter. [charm-store]: https://jujucharms.com/store -[models-config]: ./models-config.html -[charms-upgrading]: ./charms-upgrading.html -[charms-offline-deploying]: ./charms-offline-deploying.html -[charms-config]: ./charms-config.html -[charms-scaling]: ./charms-scaling.html -[network-spaces]: ./network-spaces.html -[deploying-multi-series-charms]: ./charms-deploying-advanced.html#multi--series-charms -[deploying-to-specific-machines]: ./charms-deploying-advanced.html#deploying-to-specific-machines -[deploying-to-network-spaces]: ./charms-deploying-advanced.html#deploying-to-network-spaces +[models-config]: ./models-config.md +[charms-upgrading]: ./charms-upgrading.md +[charms-offline-deploying]: ./charms-offline-deploying.md +[charms-config]: ./charms-config.md +[charms-scaling]: ./charms-scaling.md +[network-spaces]: ./network-spaces.md +[deploying-multi-series-charms]: ./charms-deploying-advanced.md#multi--series-charms +[deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines +[deploying-to-network-spaces]: ./charms-deploying-advanced.md#deploying-to-network-spaces +[#exposing-deployed-applications]: #exposing-deployed-applications diff --git a/src/en/charms-exposing.md b/src/en/charms-exposing.md deleted file mode 100644 index cce8f7829..000000000 --- a/src/en/charms-exposing.md +++ /dev/null @@ -1,71 +0,0 @@ -Title: Exposing applications - - -# Exposing applications - -By design, Juju operates a very secure environment for deploying your -applications. Even if you have deployed applications, they won't be publicly -available unless you explicitly make them so. To allow public access to -applications, the appropriate changes must be made to the cloud provider -firewall settings. As the procedure for doing this varies depending on your -cloud, Juju helpfully abstracts this into a single command, -`juju expose `. - -For example, you may have deployed a WordPress application using the relevant -charm. Once deployed, the application still cannot be accessed by the public, -so you would run: - -```bash -juju expose wordpress -``` - -Juju will then take the steps necessary to adjust firewall rules and any other -settings to expose the application via its given address. This process may take -anything from a few moments to several minutes. You can check on the current -status of your applications by running: - -```bash -juju status -``` - -This will return a status report similar to: - - - -```no-highlight -Model Controller Cloud/Region Version SLA -default gce-test google/us-east1 2.3.1 unsupported - -App Version Status Scale Charm Store Rev OS Notes -mariadb 10.1.30 active 1 mariadb jujucharms 7 ubuntu -wordpress active 1 wordpress jujucharms 5 ubuntu exposed - -Unit Workload Agent Machine Public address Ports Message -mariadb/0* active idle 1 35.196.102.182 ready -wordpress/0* active idle 0 35.227.27.40 80/tcp - -Machine State DNS Inst id Series AZ Message -0 started 35.227.27.40 juju-5b2986-0 trusty us-east1-b RUNNING -1 started 35.196.102.182 juju-5b2986-1 trusty us-east1-c RUNNING - -Relation provider Requirer Interface Type Message -mariadb:cluster mariadb:cluster mysql-ha peer -wordpress:loadbalancer wordpress:loadbalancer reversenginx peer -``` - -As you can see in the above example, the `wordpress` app is marked as 'exposed' -in the Notes column, meaning that the application is running and available to -users via its public address of 35.227.27.40. - -!!! Note: - Exposing the application does not change any DNS or other settings - which may be necessary to get your application running as you expect. - -# Unexposing an application - -To return the firewall settings and make an application non-public again, you -simply need to run the `unexpose` command. For example: - -```bash -juju unexpose wordpress -``` diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index f58324ef7..5d5338cc3 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -101,8 +101,6 @@ navigation: location: charms-working-with-units.md - title: Application metrics location: charms-metrics.md - - title: Exposing applications - location: charms-exposing.md - title: Reference From 0a670d30b6344b55541a2402b406b0bac0387165 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 1 Nov 2018 16:43:49 -0400 Subject: [PATCH 106/311] edit menu --- src/en/metadata.yaml | 12 ++++-------- src/en/troubleshooting.md | 4 ++-- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 5d5338cc3..f2b9b8ec1 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -47,6 +47,10 @@ navigation: location: charms-ha.md - title: Understanding users location: users.md + - title: Troubleshooting + location: troubleshooting.md + - title: Juju logs + location: troubleshooting-logs.md - title: Advanced topics @@ -74,14 +78,6 @@ navigation: - title: Network spaces location: network-spaces.md - - title: Troubleshooting - - children: - - title: Troubleshooting guidelines - location: troubleshooting.md - - title: Juju logs - location: troubleshooting-logs.md - - title: Miscellaneous children: diff --git a/src/en/troubleshooting.md b/src/en/troubleshooting.md index 3a9a84782..11dba650b 100644 --- a/src/en/troubleshooting.md +++ b/src/en/troubleshooting.md @@ -1,8 +1,8 @@ -Title: Troubleshooting guidelines +Title: Troubleshooting TODO: Logs from the machines/applications Review required (factoid: there are 12 instances of the word 'details') -# Troubleshooting guidelines +# Troubleshooting Juju does a brilliant job at simplifying the deployment of big software at scale. But trying to accommodate every variation of model, cloud and connection From d888b93dd13d796ebb4f2533ea0edee4486f31ab Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 1 Nov 2018 17:16:34 -0400 Subject: [PATCH 107/311] remove reference section and link pages from a central landing page --- src/en/metadata.yaml | 26 ++++---------------------- src/en/reference-documents.md | 26 ++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 22 deletions(-) create mode 100644 src/en/reference-documents.md diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index f2b9b8ec1..76cdc2a58 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -98,29 +98,11 @@ navigation: - title: Application metrics location: charms-metrics.md - - title: Reference + - title: Charm writing + location: https://docs.jujucharms.com/2.4/en/developer-getting-started - children: - - title: Release notes - location: reference-release-notes.md - - title: Juju commands - location: commands.md - - title: Juju constraints - location: reference-constraints.md - - title: Juju charm hooks - location: reference-charm-hooks.md - - title: Juju environment variables - location: reference-environment-variables.md - - title: Juju hook tools - location: reference-hook-tools.md - - title: metadata.yaml - location: authors-charm-metadata.md - - title: Charm writing - location: https://docs.jujucharms.com/2.4/en/developer-getting-started - - title: API docs - location: http://godoc.org/github.com/juju/juju/api - - title: Status values - location: reference-status.md + - title: Reference documents + location: reference-documents.md - title: Contact us location: contact-us.md diff --git a/src/en/reference-documents.md b/src/en/reference-documents.md new file mode 100644 index 000000000..56fdc82f0 --- /dev/null +++ b/src/en/reference-documents.md @@ -0,0 +1,26 @@ +Title: Reference documents + +# Reference documents + + - [Release notes][release-notes] + - [Juju commands][commands] + - [Juju constraints][reference-constraints] + - [Juju charm hooks][reference-charm-hooks] + - [Juju environment variables][reference-environment-variables] + - [Juju hook tools][reference-hook-tools] + - [metadata.yaml][authors-charm-metadata] + - [Status values][status-values] + - [API docs][api-docs] + + + + +[release-notes]: ./reference-release-notes.md +[commands]: ./commands.md +[reference-constraints]: ./reference-constraints.md +[reference-charm-hooks]: ./reference-charm-hooks.md +[reference-environment-variables]: ./reference-environment-variables.md +[reference-hook-tools]: ./reference-hook-tools.md +[authors-charm-metadata]: ./authors-charm-metadata.md +[api-docs]: http://godoc.org/github.com/juju/juju/api +[status-values]: ./reference-status.md From 3e0150b981500d8c65fe362c289cc037d6ac8700 Mon Sep 17 00:00:00 2001 From: alitvinov Date: Fri, 2 Nov 2018 16:51:28 +0300 Subject: [PATCH 108/311] Adding floating ip option --- src/en/help-openstack.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index 61a5dab5f..64b8bc09f 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -214,11 +214,15 @@ Choose the network you want the instances to boot from. You can use either the network name or the UUID with the 'network' configuration option when bootstrapping a new controller. +If there is an external network configured for instances and they could only be accessible via Floating IP on +the external network, 'external-network' and 'use-floating-ip' options should be used. + With the product-streams service running in your OpenStack Cloud, you are now ready to create a Juju controller: ```bash juju bootstrap --config network= + ``` or if the simplestream data is local: @@ -227,6 +231,13 @@ or if the simplestream data is local: juju bootstrap --metadata-source ~/simplestreams/images --config network= ``` +or with external network: + +```bash +juju bootstrap --config network= --config external-network= --config use-floating-ip=true + +``` + For a detailed explanation and examples of the `bootstrap` command see the [Creating a controller][controllers-creating] page. From 91b0de87cb385cc284036aff114948f1eaa007eb Mon Sep 17 00:00:00 2001 From: alitvinov Date: Fri, 2 Nov 2018 16:53:22 +0300 Subject: [PATCH 109/311] fix indent --- src/en/help-openstack.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index 64b8bc09f..aab87f437 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -222,7 +222,6 @@ ready to create a Juju controller: ```bash juju bootstrap --config network= - ``` or if the simplestream data is local: From 5718945379af507d249f6e957f79431b7b6b2c04 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 2 Nov 2018 10:55:01 -0400 Subject: [PATCH 110/311] add key and reword recent PR --- src/en/controllers-config.md | 6 ++++-- src/en/help-openstack.md | 19 +++++++++---------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index 9d2d4b5b5..8e75ba31f 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -1,8 +1,9 @@ Title: General configuration options -TODO: Check accuracy of key table (https://github.com/juju/juju/blob/ec89c99e51fa83cd1a2cb5e5f24e73d5b096de20/controller/config.go#L29) +TODO: Check accuracy of key table: https://github.com/juju/juju/blob/ec89c99e51fa83cd1a2cb5e5f24e73d5b096de20/controller/config.go#L29) + Check accuracy of key table: https://github.com/juju/juju/provider/*/config.go error: table's default value keys do not show up with controller-config (e.g. bootstrap-). See above note. "dynamically set by Juju" could use some explaination - ReadOnlyMethods updated from https://github.com/juju/juju/blob/2.3/apiserver/observer/auditfilter.go#L130 + ReadOnlyMethods: https://github.com/juju/juju/blob/2.3/apiserver/observer/auditfilter.go#L130 Include ability to set configuration key:value pairs by file Show how to use spaces 'juju-mgmt-space' and 'juju-ha-space' (wth 'juju bootstrap' and 'juju enable-ha') Reformat table: monospace the key names, new column for RT @@ -73,6 +74,7 @@ bootstrap-address-delay | integer | 10 | | Ho ca-cert | string | | | The certificate of the CA that signed the controller's CA certificate, in PEM format charmstore-url | string | https://api.jujucharms.com/charmstore | | Sets the Charm Store URL. controller-uuid | string | | | The key for the UUID of the controller +external-network | string | | | An OpenStack external network UUID. juju-ha-space | string | | | The name of a network space used used for MongoDB replica-set communication in a controller HA context. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). juju-mgmt-space | string | | | The name of a network space used by Juju agents to communicate with controllers. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). identity-public-key | string | | | Sets the public key of the identity manager. Feature not yet implemented. diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index aab87f437..cf49d1085 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -214,9 +214,6 @@ Choose the network you want the instances to boot from. You can use either the network name or the UUID with the 'network' configuration option when bootstrapping a new controller. -If there is an external network configured for instances and they could only be accessible via Floating IP on -the external network, 'external-network' and 'use-floating-ip' options should be used. - With the product-streams service running in your OpenStack Cloud, you are now ready to create a Juju controller: @@ -227,14 +224,16 @@ juju bootstrap --config network= or if the simplestream data is local: ```bash -juju bootstrap --metadata-source ~/simplestreams/images --config network= +juju bootstrap --config network= \ + --metadata-source ~/simplestreams/images ``` -or with external network: +or if there is an external network configured for instances that are only +accessible via floating IP: ```bash -juju bootstrap --config network= --config external-network= --config use-floating-ip=true - +juju bootstrap --config network= \ + --config external-network= --config use-floating-ip=true ``` For a detailed explanation and examples of the `bootstrap` command see the @@ -242,9 +241,9 @@ For a detailed explanation and examples of the `bootstrap` command see the ## Next steps -A controller is created with two models - the 'controller' model, which -should be reserved for Juju's internal operations, and a model named -'default', which can be used for deploying user workloads. +A controller is created with two models - the 'controller' model, which should +be reserved for Juju's internal operations, and a model named 'default', which +can be used for deploying user workloads. See these pages for ideas on what to do next: From 7dc39dce2580c3d111232a0434057715da2ef794 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 3 Nov 2018 14:44:08 -0400 Subject: [PATCH 111/311] change commands --- src/en/upgrade-series.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index da0911d7f..89101e000 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -41,11 +41,11 @@ to Ubuntu 18.04 LTS (Bionic). ### Initiating the upgrade -You initiate the upgrade with the `prepare` sub-command, the machine ID, and +You initiate the upgrade with the machine ID, the `prepare` sub-command, and the target series: ```bash -juju upgrade-series prepare 1 bionic +juju upgrade-series 1 prepare bionic ``` You will be asked to confirm the procedure. Use the `-y` option to avoid this @@ -97,7 +97,7 @@ You should now verify that the machine has been successfully upgraded. Once that's done, tell Juju that the machine is ready: ```bash -juju upgrade-series complete 1 +juju upgrade-series 1 complete ``` Sample output: From f6df9bdafa08c8df09fe86712d3f3d6f4b93a2b0 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 5 Nov 2018 12:05:09 -0500 Subject: [PATCH 112/311] swap external link for internal link --- src/en/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/en/index.md b/src/en/index.md index 96f990052..c6cee3afa 100644 --- a/src/en/index.md +++ b/src/en/index.md @@ -50,8 +50,10 @@ homepage: true
  • - Professional support + height:1.5rem;width: 1.5rem;top: + 2px;margin-right:.5rem;"> Managed solutions
  • + +[juju-experts]: https://jujucharms.com/experts +[ubuntu-advantage-servers]: https://www.ubuntu.com/support/plans-and-pricing#server +[models]: ./models.md +[ubuntu-sso]: https://login.ubuntu.com/+login +[launchpad]: https://launchpad.net/+login +[jaas-support]: https://jujucharms.com/support/create From e041706951a889619deaca689fe81f6ebb821c3e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 6 Nov 2018 10:41:44 -0500 Subject: [PATCH 115/311] final touchups after testing; can still add a container during prepare though --- src/en/upgrade-series.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 89101e000..59f7e6c66 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -14,9 +14,10 @@ TODO: warning: ubuntu code names hardcoded Starting with Juju `v.2.5.0`, to upgrade the series of a machine, the `upgrade-series` command is used. -The `upgrade-series` command does not support upgrading a controller. See below -section [Upgrading a controller machine][#upgrading-a-controller] for how to do -that using an alternate method. +The `upgrade-series` command does not support upgrading a controller. An error +will be emitted if you attempt to do so. See below section +[Upgrading a controller machine][#upgrading-a-controller] for how to do that +using an alternate method. ## Upgrading a workload machine @@ -54,17 +55,16 @@ prompt. Then output will be shown, such as: ```no-highlight -leadership pinned for application "apache2" -machine-1 started upgrade series from series xenial to series bionic -apache2/0 pre-series-upgrade hook running -apache2/0 pre-series-upgrade not found, skipping -machine-1 all necessary binaries and service files written +machine-1 started upgrade series from "xenial" to "bionic" +apache2/1 pre-series-upgrade hook running +apache2/1 pre-series-upgrade hook not found, skipping +machine-1 binaries and service files written Juju is now ready for the series to be updated. Perform any manual steps required along with "do-release-upgrade". -When ready run the following to complete the upgrade series process: +When ready, run the following to complete the upgrade series process: -juju upgrade-series complete 1 +juju upgrade-series 1 complete ``` All charms associated with the machine must support the target series in order @@ -104,10 +104,10 @@ Sample output: ```no-highlight machine-1 complete phase started -machine-1 starting all unit agents after series upgrade +machine-1 started unit agents after series upgrade apache2/0 post-series-upgrade hook running -apache2/0 post-series-upgrade not found, skipping -leadership unpinned for application "apache2" +apache2/0 post-series-upgrade hook not found, skipping +machine-1 series upgrade complete Upgrade series for machine "1" has successfully completed ``` From a3e29f4a00b08070e85680c61710a2fa1264317f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 6 Nov 2018 12:34:02 -0500 Subject: [PATCH 116/311] add more content; refactor --- src/en/experts-sla.md | 114 +++++++++++++++++++++++++++++++----------- src/en/tmp | 8 +++ 2 files changed, 92 insertions(+), 30 deletions(-) create mode 100644 src/en/tmp diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md index 8592ba63a..228751aca 100644 --- a/src/en/experts-sla.md +++ b/src/en/experts-sla.md @@ -43,7 +43,8 @@ Once you have contracted out a Juju Expert you are ready to set an SLA. This is done within Juju itself via the `sla` command, which will trigger a dialog to authenticate to your Ubuntu SSO account. -An SLA is set on a per-model basis, and specifies two key parameters: +An SLA is set on a per-model basis, and includes two key parameters in order +for support to become active: 1. Support level 1. Budget limit @@ -72,9 +73,17 @@ Model Controller Cloud/Region Version SLA Timestamp default lxd localhost/localhost 2.5-beta1 essential 19:42:28Z . . -. ``` +It is possible to simply set a support level with the `sla` command: + +```bash +juju sla -m default essential +``` + +The model's budget will then need to be set separately. We'll show how this is +done later on. + ## Changing an SLA An SLA is increased when it moves "up" levels: 'essential' to 'standard' to @@ -87,8 +96,10 @@ effective in the next monthly billing cycle. ## Budgeting managed models -SLA budgets are organized into wallets. The sum of all budgets in a wallet -cannot exceed the wallet limit. +SLA budgets are organized into *wallets*. A wallet called 'primary' is created +when the `sla` command is run for the first time. It gets hardcoded as the +default wallet. The sum of all budgets in a wallet cannot exceed the wallet +limit. ### Managing wallets @@ -111,8 +122,9 @@ Credit limit: 10000 The default wallet is shown with an asterisk "\*". SLA budgets are allocated from this wallet if the wallet name is not specified. -The credit limit is the maximum monthly limit approved to spend on SLAs. You -can submit a request to have this limit increased using this link: +The credit limit is the maximum monthly limit approved to spend on SLAs and is +determined between you and the Expert. You can submit a request to have this +limit increased using this link: [https://jujucharms.com/support/create][jaas-support] @@ -133,57 +145,99 @@ Wallet 1000 Unallocated 900 ``` -You may increase the budget limit for a model: +You may update the budget limit for a model with the `budget` command: ```bash -juju budget -m demo-izae7oj5:admin/doctest-03 250 +juju budget -m lxd:admin/default 200 ``` -``` -budget limit updated to 250 -``` +Finally, to view all the budgets associated with a wallet the `show-wallet` +command is used: ```bash -juju show-wallet personal +juju show-wallet primary ``` +Sample output: + ``` -Model Spent Budgeted By Usage -jaas:bob/marketing-campaign 0.00 250 bob 0% - -Total 0.00 250 0% -Wallet 1000 -Unallocated 750 +Model Spent Budgeted By Usage +lxd:admin/default 2.42 200 bob 1% +lxd:admin/alpha 0.00 150 bob 0% + +Total 2.42 350 1% +Wallet 1000 +Unallocated 650 ``` -The budget limit may be lowered, but not below the current spend. +The budget limit may be lowered for a model, but not below its current spent +value. -## Advanced budgeting +### Advanced budgeting -You may create additional wallets for accounting or organizational purposes. +Additional wallets may be created for accounting or organizational purposes +with the `create-wallet` command: ```bash -juju create-wallet demo-poc 200 -wallet created +juju create-wallet demo 50 ``` +Verify the creation of the new wallet by listing the wallets again: + ```bash juju wallets +``` + +Sample output: + +```no-highlight Wallet Monthly Budgeted Available Spent -demo-poc 200 0 200.00 0.00 -personal* 1000 100 1000.00 0.00 -Total 1200 100 1200.00 0.00 +demo 50 0 50.00 0.00 +primary* 1000 350 997.58 2.42 +Total 1050 350 1047.58 2.42 -Credit limit: 10000 +Credit limit: 10000 ``` -To allocate a budget from a specific wallet, use _wallet_:_limit_ when setting -the budget on an SLA. +To allocate a budget (using either the `sla` command or the `budget` command) +from a specific wallet use the form: `:`. Here are two +examples: ```bash -juju sla essential demo-poc:50 +juju sla essential demo:40 +juju budget primary:25 +``` + +## Metering + +Metering begins once the following have occurred: + + - an SLA has been assigned to a model + - a budget has been allocated to a model + - the model takes on a workload + +When metering is underway the output to the `status` command will include an +extra section: + +```no-highlight +. +. +Entity Meter status Message +model green +. +. ``` +Determining factors for actual metering costs (e.g. fixed per-hour rate, +per-unit hour, etc.) are negotiated between you and your Expert. + +## Creating a support case + +When it comes time to request help from your Expert you can file a support case +using the same URL for requesting a credit limit increase: + +[https://jujucharms.com/support/create][jaas-support] + diff --git a/src/en/tmp b/src/en/tmp new file mode 100644 index 000000000..2bb9f90e8 --- /dev/null +++ b/src/en/tmp @@ -0,0 +1,8 @@ +Model Spent Budgeted By Usage +lxd:admin/default 2.42 200 bob 1% +lxd:admin/alpha 0.00 150 bob 0% + +Total 2.42 350 1% +Wallet 1000 +Unallocated 650 + From 3938420e121d2c2c1421285c7ed67fa38e179a76 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 6 Nov 2018 13:55:09 -0500 Subject: [PATCH 117/311] add info on status output re metering --- src/en/experts-sla.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md index 228751aca..82a61da1c 100644 --- a/src/en/experts-sla.md +++ b/src/en/experts-sla.md @@ -228,6 +228,14 @@ model green . ``` +A 'Meter' value of **green** (displayed with a green colour in the terminal) +indicates that the customer’s payment method is in good standing. A value of +**amber** indicates a condition puts future payment for continued use at risk +(e.g. spending is occurring at a rate likely to exceed the monthly limit). A +value of **red** indicates that continued use of the workload will not be paid +for (e.g. budget limit exceeded, problem with payment method). The 'Message' +column will be updated with appropriate details. + Determining factors for actual metering costs (e.g. fixed per-hour rate, per-unit hour, etc.) are negotiated between you and your Expert. From e40697c9afc8efe8772fff346727d5124cc68258 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 6 Nov 2018 13:57:50 -0500 Subject: [PATCH 118/311] remove tmp file --- src/en/tmp | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 src/en/tmp diff --git a/src/en/tmp b/src/en/tmp deleted file mode 100644 index 2bb9f90e8..000000000 --- a/src/en/tmp +++ /dev/null @@ -1,8 +0,0 @@ -Model Spent Budgeted By Usage -lxd:admin/default 2.42 200 bob 1% -lxd:admin/alpha 0.00 150 bob 0% - -Total 2.42 350 1% -Wallet 1000 -Unallocated 650 - From 62a0a73f2071ad043b8d89309e1557b80918927c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 7 Nov 2018 12:30:49 -0500 Subject: [PATCH 119/311] edit based on GH review --- src/en/experts-sla.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md index 82a61da1c..36556d858 100644 --- a/src/en/experts-sla.md +++ b/src/en/experts-sla.md @@ -2,17 +2,18 @@ Title: Managed solutions # Managed solutions -A Juju Expert is a partner backed by professional support at Canonical Ltd. -Such a partner deploys and supports an infrastructure based on Juju. We call -this a *managed solution*. +One professional support option available to you as a Juju operator is to +enlist the help of a *Juju Expert*. + +A Juju Expert is a support partner, backed by Canonical Ltd, which deploys and +supports infrastructure based on Juju. We call this type of arrangement a +*managed solution*. Any support requests beyond the build, workload, and operation of a particular -solution can be escalated to Canonical by means of their Ubuntu Advantage -support framework. Prime examples of such requests are for issues relating to -Juju itself, Ubuntu-specific software, or the operating system kernel. The -escalated support case will be treated by Canonical at the same support level -currently ascribed to the partner. Hence, support level names used by both a -Juju Expert and by Canonical are the same: +solution can be escalated, by the Expert, to Canonical by means of their Ubuntu +Advantage support framework. The escalated support case will be treated by +Canonical at the same support level currently ascribed to the partner. Hence, +support level names used by both a Juju Expert and by Canonical are the same: - Essential - Standard @@ -25,8 +26,8 @@ The Juju Expert will provide details such as support levels and costs on a per-solution basis but ultimately an SLA will be conferred upon a specific Juju model (see [Models][models]). -Consult the external [Juju Experts][juju-experts] page to find a managed -solution partner for your project. +Consult the [Juju Experts][juju-experts] page to find a managed solution +partner for your project. ## Requirements @@ -242,7 +243,7 @@ per-unit hour, etc.) are negotiated between you and your Expert. ## Creating a support case When it comes time to request help from your Expert you can file a support case -using the same URL for requesting a credit limit increase: +here: [https://jujucharms.com/support/create][jaas-support] From b22ef051287bd221cadcc3949b797d6781e6e4dd Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 7 Nov 2018 14:56:41 -0500 Subject: [PATCH 120/311] update release notes and install page --- src/en/reference-install.md | 16 +++--- src/en/reference-release-notes.md | 84 +++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 8 deletions(-) diff --git a/src/en/reference-install.md b/src/en/reference-install.md index 9368e7b13..9663c12e8 100644 --- a/src/en/reference-install.md +++ b/src/en/reference-install.md @@ -7,9 +7,9 @@ distributions, macOS, and Windows. Development releases are also available for testing. Read on for how to install a stable or development version of Juju on your chosen platform. -## Version 2.4.4 +## Version 2.4.5 -The most recent stable version of Juju is 2.4.4. This is the version we +The most recent stable version of Juju is 2.4.5. This is the version we recommend for production use. See the [Release Notes][release-notes-2]. ### Ubuntu @@ -79,7 +79,7 @@ sudo snap install juju --classic For CentOS, you can download Juju from the following archive and install it manually: -[**juju-2.4.4-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) +[**juju-2.4.5-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) ### macOS @@ -100,7 +100,7 @@ brew upgrade juju A Windows installer is available for Juju and can be found here: -[**juju-setup-2.4.4-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) +[**juju-setup-2.4.5-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) ## Development releases @@ -167,9 +167,9 @@ instructions on how to build Juju from source. [snapcraft]: https://snapcraft.io [snapd-install]: https://snapcraft.io/docs/core/install [juju-new-bug]: https://bugs.launchpad.net/juju/+filebug -[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-setup-2.4.4-signed.exe -[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-setup-2.4.4-signed.exe/+md5 -[juju-centos]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-2.4.4-centos7.tar.gz -[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.4/+download/juju-2.4.4-centos7.tar.gz/+md5 +[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-setup-2.4.5-signed.exe +[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-setup-2.4.5-signed.exe/+md5 +[juju-centos]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-2.4.5-centos7.tar.gz +[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-2.4.5-centos7.tar.gz/+md5 [juju-launchpad-binaries]: https://launchpad.net/juju/+series [centos-and-other-linuxes]: #centos-and-other-linuxes diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index cb623ca0f..e633662e4 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -5,6 +5,90 @@ Title: Juju Release Notes This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available [here][release-notes-1]. +^# Juju 2.4.5 + + This is primarily a bugfix release for the 2.4 series but comes with one new + feature and several improvements. + + The `export-bundle` feature is cleared from the feature flag. Many of the + bugs involve helping Juju deal better at scale with thousands of units + running in models on a single controller. On restart Juju is now smarter + about retrying randomization and backing off retries along with other scale + based improvements. + + ## Enhancements + + **New `export-bundle` command** + + Juju now has an `export-bundle` command that generates a bundle from a given + model. In any model use this command to output a reusable description of the + model to deploy a second time, to backup and check for differences, or to + submit to the Charm Store. + + **Controller API port configuration key** + + The new configuration key 'controller-api-port' allows controller connections + to occur on a separate port than that used by other agent connections, and + the standard port won't accept connections until the controllers are + connected. This can be of use when the number of units is very large + (thousands). When the controller agent restarts it helps make sure the HA + controllers are all up and synchronised before handling connection requests + from the units. + + juju bootstrap --config controller-api-port=17071 cloud-name controller-name + + This feature can be implemented in real time (i.e. post-bootstrap): + + juju controller-config controller-api-port=17071 + + This feature is disabled by setting the port to zero: + + juju controller-config controller-api-port=0 + + In a future release this key will become required and immutable like the + normal 'api-port' key. + + **Scale improvements** + + Several improvements have been made to deal with the load caused by a large + number of agents. Each agent's workers now have an exponential backoff on + failure. Additionally, agent requests are now more evenly distributed over + controllers. + + ## Other fixes + + This release also includes the following important fixes: + + - [LP #1793245](https://bugs.launchpad.net/juju/2.4/+bug/1793245) - addresses agents randomizing their connections and exponential backoff + - [LP #1795499](https://bugs.launchpad.net/juju/2.4/+bug/1795499) - cross model relation breaks after removing relation + - [LP #1796106](https://bugs.launchpad.net/juju/2.4/+bug/1796106) - can’t bring up containers on a manually provisioned machine + + For the full list of fixes and additions, see the + [2.4.5 milestone](https://launchpad.net/juju/+milestone/2.4.5). + + ## Get Juju + + The easiest way to install Juju is by using the `snap` package: + + sudo snap install juju --classic + + Those already using the 'stable' snap channel (the default as per the above + command) should be upgraded automatically. Other packages are available for a + variety of platforms (see the [install documentation][reference-install]). + + ## Feedback appreciated + + Let us know how you're using Juju or of any questions you may have. You can + join us on [Discourse][juju-discourse-forum], send us a message on Twitter + (hashtag `#jujucharms`), or talk to us in the `#juju` IRC channel on + freenode. + + ## More information + + To learn more about Juju visit our home page at + [https://jujucharms.com](https://jujucharms.com). + + ^# Juju 2.4.4 The Juju team is pleased to announce the release of Juju 2.4.4. From 8c289931567bc62c382dac3bed11abf09a466e73 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 09:37:28 -0500 Subject: [PATCH 121/311] depracate old oracle --- src/en/clouds-oci.md | 32 ++++++++++++++------------------ src/en/clouds.md | 38 +++++++++++++++++--------------------- 2 files changed, 31 insertions(+), 39 deletions(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index f239704f3..f3110b426 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -1,7 +1,7 @@ -Title: Using Oracle Cloud Infrastructure with Juju -TODO: Review required: 2.5 changes still to come (baked-in, then test trial accounts) +Title: Using Oracle OCI with Juju +TODO: Review required: test trial accounts -# Using Oracle Cloud Infrastructure with Juju +# Using Oracle OCI with Juju Juju has built-in support for [Oracle Cloud Infrastructure][oracle-oci] (OCI), Oracle's public cloud. This means that there is no need to add the OCI cloud @@ -75,33 +75,29 @@ OCIDs are required for the following objects: They are all gathered via Oracle's web [Console][oracle-oci-console]. -**Tenancy OCID** -The Tenancy OCID is found by clicking in the top-right corner user icon and -choosing the 'Tenancy: your_username' menu entry. The resulting page will -provide the information. +**User OCID** +The User OCID is found by clicking in the top-left menu and choosing 'Identity' +and then 'Users'. The resulting page will provide the information. Here, we'll assign this value to a variable so we can refer to it later: -`OCID_TENANCY=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` +`OCID_USER=ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq` -**User OCID** -The User OCID is found by clicking in the top-left menu and choosing 'Identity' -and then 'Users'. The resulting page will provide the information. +**Tenancy OCID** +The Tenancy OCID is found on the same page but in the sub-menu +'Compartments'. The resulting page will provide the information. Again, we'll assign this to a variable: -`OCID_USER=ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq` +`OCID_TENANCY=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` **Compartment OCID** -The Compartment OCID is found on the same page but in the sub-menu -'Compartments': +The Compartment OCID is found on the same page: `OCID_COMPARTMENT=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` -Notice that the Tenancy and Compartment values are identical. This is because, -in this example, we decided to use the compartment provided to us by default -(the *root Compartment*). If you created a new compartment at the "Preparing -your OCI account" step then your values should be different. +In this example, for the User OCID, we decided to use the compartment provided +to us by default (the *root Compartment*). ### Upload the public key diff --git a/src/en/clouds.md b/src/en/clouds.md index 4b483f860..810a56263 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -9,11 +9,10 @@ table_of_contents: True Juju supports a wide variety of clouds. In addition, many of these are known to Juju out of the box. They are Amazon AWS, Microsoft Azure, Google GCE, Oracle -Compute, Rackspace, Joyent, and LXD. +OCI, Rackspace, Joyent, and LXD. The remaining supported clouds do need to be added to Juju, and, as will be shown, it is simply done. They are VMware vSphere, OpenStack, MAAS, and Manual. -An Oracle *trial* account also needs to be added. Once your cloud is known to Juju, whether by default or due to it being added, the next step is to add your cloud credentials to Juju. The exception is for a @@ -25,8 +24,7 @@ clouds are added. You can still get started by selecting your cloud here: - [Amazon AWS][clouds-aws] - [Microsoft Azure][clouds-azure] - [Google GCE][clouds-google] - - [Oracle Compute][clouds-oracle] - - [Oracle Cloud Infrastructure][clouds-oci] + - [Oracle OCI][clouds-oci] - [Rackspace][clouds-rackspace] - [Joyent][clouds-joyent] - [LXD][clouds-lxd] @@ -47,24 +45,23 @@ juju clouds This will return a list very similar to: ```no-highlight -Cloud Regions Default Type Description -aws 14 us-east-1 ec2 Amazon Web Services -aws-china 1 cn-north-1 ec2 Amazon China -aws-gov 1 us-gov-west-1 ec2 Amazon (USA Government) -azure 24 centralus azure Microsoft Azure -azure-china 2 chinaeast azure Microsoft Azure China -cloudsigma 5 hnl cloudsigma CloudSigma Cloud -google 7 us-east1 gce Google Cloud Platform -joyent 6 eu-ams-1 joyent Joyent Cloud -oracle 5 uscom-central-1 oracle Oracle Cloud -rackspace 6 dfw rackspace Rackspace Cloud -localhost 1 localhost lxd LXD Container Hypervisor +Cloud Regions Default Type Description +aws 15 us-east-1 ec2 Amazon Web Services +aws-china 1 cn-north-1 ec2 Amazon China +aws-gov 1 us-gov-west-1 ec2 Amazon (USA Government) +azure 26 centralus azure Microsoft Azure +azure-china 2 chinaeast azure Microsoft Azure China +cloudsigma 5 hnl cloudsigma CloudSigma Cloud +google 13 us-east1 gce Google Cloud Platform +joyent 6 eu-ams-1 joyent Joyent Cloud +oracle 4 us-phoenix-1 oci Oracle Cloud Infrastructure +rackspace 6 dfw rackspace Rackspace Cloud +localhost 1 localhost lxd LXD Container Hypervisor ``` -Each line represents a backing cloud that Juju can interact with. It gives the -cloud name, the number of cloud regions Juju is aware of, the default region -(for the current Juju client), the type/API used to control it, and a brief -description. +Each line represents a cloud that Juju can interact with. It gives the cloud +name, the number of cloud regions Juju is aware of, the default region (for the +current Juju client), the type/API used to control it, and a brief description. !!! Important: The cloud name (e.g. 'aws', 'localhost') is what you will use in any @@ -192,7 +189,6 @@ Here are some examples of manually adding a cloud: [clouds-aws]: ./help-aws.md [clouds-azure]: ./help-azure.md [clouds-google]: ./help-google.md -[clouds-oracle]: ./help-oracle.md [clouds-oci]: ./clouds-oci.md [clouds-rackspace]: ./help-rackspace.md [clouds-joyent]: ./help-joyent.md From 8a9ede27d7df2c9f4bb4691fa065e281e61fdcb4 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 10:32:19 -0500 Subject: [PATCH 122/311] add keys; minor improvements --- src/en/controllers-config.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index 8e75ba31f..5d57a98f9 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -59,7 +59,8 @@ real-time (post-bootstrap) is tagged with **[RT]**. | Key | Type | Default | Valid values | Purpose | |:---------------------------|---------|----------|--------------------------|:---------| -api-port | integer | 17070 | | The port to use for connecting to the API +api-port | integer | 17070 | | The port to use for connecting controller and non-controller agents to controller agents (the controller API). See 'controller-api-port'. +api-port-open-delay | string | | 10s, etc. | The delay before the controller API port will accept non-controller agent connections. Enabled only if 'controller-api-port' is set. auditing-enabled **[RT]** | bool | true | false/true | Sets whether audit logging is enabled. Can be toggled for an existing controller. audit-log-capture-args **[RT]** | bool | false | false/true | Sets whether the audit log will contain the arguments passed to API methods. Can be toggled for an existing controller. audit-log-exclude-methods **[RT]** | string | ReadOnlyMethods | [Some.Method,...] | What information to exclude from the audit log. Can be set for an existing controller. See [additional info][#excluding-information-audit-log]. @@ -73,7 +74,8 @@ bootstrap-retry-delay | integer | 5 | | Ho bootstrap-address-delay | integer | 10 | | How often in seconds to refresh controller addresses from the API server ca-cert | string | | | The certificate of the CA that signed the controller's CA certificate, in PEM format charmstore-url | string | https://api.jujucharms.com/charmstore | | Sets the Charm Store URL. -controller-uuid | string | | | The key for the UUID of the controller +controller-api-port | integer | | | The port to use for connecting controller agents to one another. See 'api-port-open-delay'. +controller-uuid | string | | | The UUID of the controller external-network | string | | | An OpenStack external network UUID. juju-ha-space | string | | | The name of a network space used used for MongoDB replica-set communication in a controller HA context. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). juju-mgmt-space | string | | | The name of a network space used by Juju agents to communicate with controllers. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). @@ -87,10 +89,10 @@ max-txn-log-size | string | 10M | 100M, 1G, etc. | Se mongo-memory-profile | string | low | low/default | Sets whether MongoDB uses the least possible memory or the default MongoDB memory profile network | string | | | An OpenStack network UUID. set-numa-control-policy | bool | false | false/true | Sets whether numactl is preferred for running processes with a specific NUMA (Non-Uniform Memory Architecture) scheduling or memory placement policy for multiprocessor systems where memory is divided into multiple memory nodes -policy-target-group | string | | | An OpenStack PTG ID. Use with key 'use-openstack-gbp'. +policy-target-group | string | | | An OpenStack PTG ID. Use with 'use-openstack-gbp'. state-port | integer | 37017 | | The port to use for mongo connections use-floating-ip | bool | false | | Use with OpenStack. Sets whether a floating IP address is required in order for nodes to be assigned a public IP address. -use-openstack-gbp | bool | false | | Sets whether OpenStack GBP (Group-Based Policy) is enabled. Use with key 'policy-target-group'. +use-openstack-gbp | bool | false | | Sets whether OpenStack GBP (Group-Based Policy) is enabled. Use with 'policy-target-group'. ### Controller-related spaces From e8ca658e862c155a2c8069e7ed65bd9ee1228eea Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 10:34:00 -0500 Subject: [PATCH 123/311] specify real-time --- src/en/controllers-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/controllers-config.md b/src/en/controllers-config.md index 5d57a98f9..8f65c069d 100644 --- a/src/en/controllers-config.md +++ b/src/en/controllers-config.md @@ -60,7 +60,7 @@ real-time (post-bootstrap) is tagged with **[RT]**. | Key | Type | Default | Valid values | Purpose | |:---------------------------|---------|----------|--------------------------|:---------| api-port | integer | 17070 | | The port to use for connecting controller and non-controller agents to controller agents (the controller API). See 'controller-api-port'. -api-port-open-delay | string | | 10s, etc. | The delay before the controller API port will accept non-controller agent connections. Enabled only if 'controller-api-port' is set. +api-port-open-delay **[RT]** | string | | 10s, etc. | The delay before the controller API port will accept non-controller agent connections. Enabled only if 'controller-api-port' is set. auditing-enabled **[RT]** | bool | true | false/true | Sets whether audit logging is enabled. Can be toggled for an existing controller. audit-log-capture-args **[RT]** | bool | false | false/true | Sets whether the audit log will contain the arguments passed to API methods. Can be toggled for an existing controller. audit-log-exclude-methods **[RT]** | string | ReadOnlyMethods | [Some.Method,...] | What information to exclude from the audit log. Can be set for an existing controller. See [additional info][#excluding-information-audit-log]. @@ -74,7 +74,7 @@ bootstrap-retry-delay | integer | 5 | | Ho bootstrap-address-delay | integer | 10 | | How often in seconds to refresh controller addresses from the API server ca-cert | string | | | The certificate of the CA that signed the controller's CA certificate, in PEM format charmstore-url | string | https://api.jujucharms.com/charmstore | | Sets the Charm Store URL. -controller-api-port | integer | | | The port to use for connecting controller agents to one another. See 'api-port-open-delay'. +controller-api-port **[RT]** | integer | | | The port to use for connecting controller agents to one another. See 'api-port-open-delay'. controller-uuid | string | | | The UUID of the controller external-network | string | | | An OpenStack external network UUID. juju-ha-space | string | | | The name of a network space used used for MongoDB replica-set communication in a controller HA context. Effectively acts as a machine constraint. See [additional info below](#controller-related-spaces). From 8237302d12abd83bbf20631a821007b184c49fc8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 12:47:31 -0500 Subject: [PATCH 124/311] edit based on GH review --- src/en/experts-sla.md | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md index 36556d858..e33401f02 100644 --- a/src/en/experts-sla.md +++ b/src/en/experts-sla.md @@ -5,22 +5,17 @@ Title: Managed solutions One professional support option available to you as a Juju operator is to enlist the help of a *Juju Expert*. -A Juju Expert is a support partner, backed by Canonical Ltd, which deploys and -supports infrastructure based on Juju. We call this type of arrangement a -*managed solution*. +A Juju Expert is a Canonical Ltd. support partner, which deploys and supports +infrastructure based on Juju. We call this type of arrangement a *managed +solution*. Any support requests beyond the build, workload, and operation of a particular solution can be escalated, by the Expert, to Canonical by means of their Ubuntu Advantage support framework. The escalated support case will be treated by -Canonical at the same support level currently ascribed to the partner. Hence, -support level names used by both a Juju Expert and by Canonical are the same: - - - Essential - - Standard - - Advanced - -See [Ubuntu Advantage for Servers][ubuntu-advantage-servers] for more -information on Canonical support levels. +Canonical at the same support level currently ascribed to the partner +(Essential, Standard, or Advanced). See +[Ubuntu Advantage for Servers][ubuntu-advantage-servers] for more information +on Canonical support levels. The Juju Expert will provide details such as support levels and costs on a per-solution basis but ultimately an SLA will be conferred upon a specific Juju @@ -29,6 +24,9 @@ model (see [Models][models]). Consult the [Juju Experts][juju-experts] page to find a managed solution partner for your project. +**The remainder of this page describes how a Juju Expert would administer a +managed solution for you.** + ## Requirements The following requirements need to be met before setting an SLA for the first @@ -40,12 +38,10 @@ time: ## Setting an SLA -Once you have contracted out a Juju Expert you are ready to set an SLA. This is -done within Juju itself via the `sla` command, which will trigger a dialog to -authenticate to your Ubuntu SSO account. +An SLA is set within Juju itself, on a per-model basis, via the `sla` command, +which will trigger a dialog to authenticate to your Ubuntu SSO account. -An SLA is set on a per-model basis, and includes two key parameters in order -for support to become active: +Two key parameters are needed in order for support to become active: 1. Support level 1. Budget limit @@ -123,9 +119,8 @@ Credit limit: 10000 The default wallet is shown with an asterisk "\*". SLA budgets are allocated from this wallet if the wallet name is not specified. -The credit limit is the maximum monthly limit approved to spend on SLAs and is -determined between you and the Expert. You can submit a request to have this -limit increased using this link: +The credit limit is the maximum monthly limit approved to spend on SLAs. You +can submit a request to have this limit increased using this link: [https://jujucharms.com/support/create][jaas-support] @@ -238,7 +233,7 @@ for (e.g. budget limit exceeded, problem with payment method). The 'Message' column will be updated with appropriate details. Determining factors for actual metering costs (e.g. fixed per-hour rate, -per-unit hour, etc.) are negotiated between you and your Expert. +per-unit hour, etc.) are negotiated between the customer and the Expert. ## Creating a support case From 5d8f8cbbd228fc2f705f297790da5b8f171cf9c6 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 13:38:16 -0500 Subject: [PATCH 125/311] final --- src/en/experts-sla.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/en/experts-sla.md b/src/en/experts-sla.md index e33401f02..a173f56f1 100644 --- a/src/en/experts-sla.md +++ b/src/en/experts-sla.md @@ -119,10 +119,10 @@ Credit limit: 10000 The default wallet is shown with an asterisk "\*". SLA budgets are allocated from this wallet if the wallet name is not specified. -The credit limit is the maximum monthly limit approved to spend on SLAs. You -can submit a request to have this limit increased using this link: - -[https://jujucharms.com/support/create][jaas-support] +The *credit limit* is the maximum monthly limit approved to spend on SLAs. You +can submit a request to Canonical to have this limit increased. This is done +via an escalated support case. See section +[Escalating a support case][#escalating-a-support-case]. View the budgets allocated from a wallet with the `show-wallet` command: @@ -235,13 +235,16 @@ column will be updated with appropriate details. Determining factors for actual metering costs (e.g. fixed per-hour rate, per-unit hour, etc.) are negotiated between the customer and the Expert. -## Creating a support case +## Escalating a support case -When it comes time to request help from your Expert you can file a support case +When it comes time to request help from Canonical you can file a support case here: [https://jujucharms.com/support/create][jaas-support] +You would also request an increase to the monthly credit limit via a support +case. + @@ -251,3 +254,4 @@ here: [ubuntu-sso]: https://login.ubuntu.com/+login [launchpad]: https://launchpad.net/+login [jaas-support]: https://jujucharms.com/support/create +[#escalating-a-support-case]: #escalating-a-support-case From f03e08b2ddf88f413ab121bf6961b6ba385e4d88 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 14:27:37 -0500 Subject: [PATCH 126/311] remove files and empty whats-new --- src/en/howto.md | 15 -------- src/en/juju-managing.md | 11 ------ src/en/whats-new.md | 85 ++--------------------------------------- 3 files changed, 3 insertions(+), 108 deletions(-) delete mode 100644 src/en/howto.md delete mode 100644 src/en/juju-managing.md diff --git a/src/en/howto.md b/src/en/howto.md deleted file mode 100644 index cc93fb708..000000000 --- a/src/en/howto.md +++ /dev/null @@ -1,15 +0,0 @@ -Title: Getting things done - -# Getting things done - -Juju is not all about marvelling about how great service orchestration is, it's -actually about getting things done. While the documentation provides you with -instructions on how Juju works, this section is all about putting those commands -together to do something useful. Prepare to get things done! - -- [Configure metrics gathering with Prometheus](./howto-prometheus.html) -- [Set up a private cloud with Simplestreams](./howto-privatecloud.html) -- [Update the series of a juju controller or workload](./howto-updateseries.html) - -Got an idea for something to add here? Check out [how to contribute to the -docs](contributing.html) diff --git a/src/en/juju-managing.md b/src/en/juju-managing.md deleted file mode 100644 index 0f30cd260..000000000 --- a/src/en/juju-managing.md +++ /dev/null @@ -1,11 +0,0 @@ -Title: Managing Juju - - -# Managing Juju - -Distinct from deploying and managing Juju Charms, there are many Juju commands -which deal with the management of Juju itself, covering actions from disabling -certain commands to enabling high availability for the Juju controller. - -These topics are covered in the pages listed under this topic in the navigation -menu on the left. diff --git a/src/en/whats-new.md b/src/en/whats-new.md index f8182a089..6dd3a9907 100644 --- a/src/en/whats-new.md +++ b/src/en/whats-new.md @@ -1,84 +1,5 @@ -Title: What's new in 2.4 +Title: What's new in 2.5 -# What's new in 2.4 - -The latest release of Juju has focused a little more on under-the-hood -improvements, making Juju much more efficient at scale, but there are -some major changes you should know about, which we have summarised here. - - -For full details on this release, see the [2.4 release notes][release-notes]. - -If you are new to Juju, you will probably want to read the -[Getting started][getting-started] guide first. - - - -## 18.04 LTS (Bionic) support - -Juju now fully supports running both containers and workloads on the latest -LTS release of Ubuntu! Currently, the default is to use 16.04 LTS (Xenial), -but you can choose a different series when bootstrapping or deploying. For -example, to create a new controller: - -```bash -juju bootstrap --bootstrap-series=bionic localhost localcloud -``` - -Workloads will automatically be deployed on the newest available series -supported by the charm. - - -## Controller network spaces - -Two new controller configuration settings have been introduced to make it -easier to specify which network spaces and/or subnets should be used for -communication with the controller by workload agents, or between -controllers in the case of a Highly Available setup: - - * juju-mgmt-space - * juju-ha-space - -For more information on how to use these new options, please read the -documentation on [configuring controllers][controllers-config]. - -## Model Ownership - -In previous releases, the user who originally created a new model had special -privileges over it. With this release, multiple users can be given admin -status, and any user can have admin status taken away, so there is -nothing unique about the original creator. - -## Cloud credential changes - -Credentials are essential for the Juju controller to authenticate and perform -actions on the underlying cloud. Juju has always kept credentials remotely on -the controller in addition to credentials stored locally by the Juju client. -This isn't going to change, but the ambiguity of where particular credentials -are stored has caused some confusion, so a new command has been added. - -To discover the credentials for the current user and cloud, run: - -```bash -juju show-credentials -``` - -Additionally, the `show-model` command now outputs some additional information -on credentials, for example: - -```bash - credential: - name: default - owner: admin - cloud: aws -``` -will appear in the YAML output. - - - - -[getting-started]: ./getting-started.md -[release-notes]: ./reference-release-notes.md#juju_2.4.0 -[controllers-config]: ./controllers-config.md -[credential-command]: ./commands.md#show-credentials +# What's new in 2.5 +*Stay tuned.* From f66ffd9abaeca544ba20b5884c422d6e0203acc8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 8 Nov 2018 14:54:51 -0500 Subject: [PATCH 127/311] small fixes --- src/en/index.md | 2 +- src/en/tut-lxd.md | 4 ++-- src/en/tut-users.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/en/index.md b/src/en/index.md index c6cee3afa..b46b8b72e 100644 --- a/src/en/index.md +++ b/src/en/index.md @@ -33,7 +33,7 @@ homepage: true

    Explore Juju

    diff --git a/src/en/tut-lxd.md b/src/en/tut-lxd.md index 1ed5eba31..dcce8d3c1 100644 --- a/src/en/tut-lxd.md +++ b/src/en/tut-lxd.md @@ -1,9 +1,9 @@ -Title: Using Juju locally with LXD +Title: Using Juju locally (LXD) TODO: Warning: Ubuntu release versions hardcoded tutorials at the bottom may get renamed sudo is not required for lxd > 3.0.1 (edit when appropriate) -# Using Juju locally with LXD +# Using Juju locally (LXD) This guide will get you started quickly with Juju by setting up everything you need on a single [Ubuntu 18.04 LTS][Bionic-download] (Bionic) system. It does diff --git a/src/en/tut-users.md b/src/en/tut-users.md index f74762299..7c4ff3c2d 100644 --- a/src/en/tut-users.md +++ b/src/en/tut-users.md @@ -1,8 +1,8 @@ -Title: Multi-user cloud +Title: A multi-user cloud TODO: change screenshot username from degville to newuser add link to a table showing permissions for each type of user -# Multi-user cloud +# A multi-user cloud Juju is great at deploying applications to the cloud, but it is even better when others can join in too! From 5653dfed1577669ea0f72491baee1dc5b85fa911 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 9 Nov 2018 15:51:45 -0500 Subject: [PATCH 128/311] lots of testing --- src/en/clouds-oci.md | 210 +++++++++++-------------------- src/en/credentials.md | 21 +--- src/en/help-oracle.md | 279 ------------------------------------------ 3 files changed, 80 insertions(+), 430 deletions(-) delete mode 100644 src/en/help-oracle.md diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index f3110b426..6ee53c25c 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -1,22 +1,26 @@ Title: Using Oracle OCI with Juju -TODO: Review required: test trial accounts +TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1802577 (add '-aes128' to command that creates the key if fixed) # Using Oracle OCI with Juju -Juju has built-in support for [Oracle Cloud Infrastructure][oracle-oci] (OCI), -Oracle's public cloud. This means that there is no need to add the OCI cloud -to Juju. An exception to this is if you are using a trial account. Both types -of accounts, paid and trial, are covered here. +Juju already has knowledge of the OCI cloud +([Oracle Cloud Infrastructure][oracle-oci]), which means adding your Oracle +account to Juju is quick and easy. -This page will cover the following steps: +You can see more specific information on Juju's OCI support (e.g. the +supported regions) by running: - 1. For trial accounts, add the OCI cloud to Juju. - 1. Add credentials to Juju so it can make use of your OCI account. - 1. Create the Juju controller. +```bash +juju show-cloud oracle +``` -!!! Note: - Oracle's [SDK tools][oracle-oci-cli] can also be used to manage your OCI - account. +If at any point you believe Juju's information is out of date (e.g. Oracle just +announced support for a new region), you can update Juju's public cloud data by +running: + +```bash +juju update-clouds +``` ## Understanding and preparing your OCI account @@ -32,6 +36,10 @@ most certainly need to do this for both organisational and security reasons. To organise your Tenancy and its associated compartments read Oracle's [Setting up your Tenancy][oracle-oci-tenancy] page. +!!! Note: + Oracle's [SDK tools][oracle-oci-cli] can also be used to manage your OCI + account. + ## Gathering information The following bits of information need to be gathered: @@ -56,14 +64,21 @@ openssl rsa -pubout -in ~/.oci/oci_ssl_key_private.pem -out ~/.oci/oci_ssl_key_p openssl rsa -pubout -outform DER -in ~/.oci/oci_ssl_key_private.pem | openssl md5 -c ``` -The last command will print the fingerprint of the private key to your screen. +The first `openssl` invocation will create an encrypted private key and will +therefore prompt you for a passphrase. You will need this for later. Omit +option `-aes128` to disable encryption. + +The last command will output the fingerprint of the private key. -We'll later make reference to the private key, the public key, and the -fingerprint using these variables: +The private key is now in file `~/.oci/oci_ssl_key_private.pem` and the public +key is in file `~/.oci/oci_ssl_key_public.pem`. + +We'll later make reference to the private key, the fingerprint, and the +passphrase using these variables, respectively: `$SSL_PRIVATE_KEY` -`$SSL_PUBLIC_KEY` -`$SSL_PRIVATE_KEY_FINGERPRINT` +`$SSL_PRIVATE_KEY_FINGERPRINT` +`$SSL_PRIVATE_KEY_PASSPHRASE` ### Oracle Cloud Identifiers (OCIDs) @@ -75,19 +90,22 @@ OCIDs are required for the following objects: They are all gathered via Oracle's web [Console][oracle-oci-console]. +!!! Note: + The below instructions for navigating the Oracle web interface assume you + are the account administrator. If this is not the case, your experience may + differ. In particular, you may need to access information in the top-right + corner (look for "User Settings"). + **User OCID** The User OCID is found by clicking in the top-left menu and choosing 'Identity' -and then 'Users'. The resulting page will provide the information. - -Here, we'll assign this value to a variable so we can refer to it later: +and then sub-menu 'Users'. Here, we'll assign this value to a variable so we +can refer to it later: `OCID_USER=ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq` **Tenancy OCID** -The Tenancy OCID is found on the same page but in the sub-menu -'Compartments'. The resulting page will provide the information. - -Again, we'll assign this to a variable: +The Tenancy OCID is found similarly but in the sub-menu 'Compartments'. Again, +we'll assign this to a variable: `OCID_TENANCY=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` @@ -96,108 +114,22 @@ The Compartment OCID is found on the same page: `OCID_COMPARTMENT=ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia` -In this example, for the User OCID, we decided to use the compartment provided -to us by default (the *root Compartment*). - -### Upload the public key - -Upload the public key (under 'API Keys') - -## Trial accounts - -As mentioned, you will need to add your Oracle cloud to Juju if you're using a -trial account. This requires a 'REST Endpoint'. To get this, navigate to 'My -Account URL', scroll down to 'Oracle Compute Cloud Service', and click on it. -The resulting page will look similar to this: - -![REST endpoint](./media/oracle_myservices-endpoint-2.png) +In this example, for the Compartment OCID, we decided to use the compartment +provided to us by default (the *root Compartment*). Notice how it's the same as +the Tenancy OCID. -There may be multiple endpoints. In that case, trial and error may be needed -below (hint: the endpoint domain should be resolvable using DNS). +### Provide the public SSL key to Oracle -Use the interactive `add-cloud` command to add your OCI cloud to Juju's list -of clouds. You will need to supply a name you wish to call your cloud and -your region. - -For the manual method of adding an OCI cloud, see below section -[Manually adding an OCI cloud][#clouds-oci-manual]. - -```bash -juju add-cloud -``` - -Example user session: - -```no-highlight -Cloud Types - lxd - maas - manual - oci - openstack - oracle - vsphere +In order for the SSL keypair to be of any use the public key must be placed on +the remote end. -Select cloud type: oci - -Enter a name for your oci cloud: oci-test - -Enter region name: us-ashburn-1 - -Enter another region? (y/N): N - -Cloud "oci-test" successfully added - -You may need to `juju add-credential oci-test' if your cloud needs additional credentials -then you can bootstrap with 'juju bootstrap oci-test' -``` - -Now confirm the successful addition of the cloud: - -```bash -juju clouds -``` - -Here is a partial output: - -```no-highlight -Cloud Regions Default Type Description -. -. -. -oci-test 1 us-ashburn-1 oci -``` - -### Manually adding an OCI cloud - -This example covers manually adding an OCI cloud to Juju (see -[Adding clouds manually][clouds-adding-manually] for background information). - -The manual method necessitates the use of a [YAML-formatted][yaml] -configuration file. Here is an example: - -```yaml -clouds: - oci-test: - type: oci - auth-types: [httpsig] - regions: - us-ashburn-1: {} -``` - -Here we've used 'oci-test' and 'us-ashburn-1' for cloud name and cloud region -respectively. Your region is listed in the Console. - -To add cloud 'oci-test', assuming the configuration file is `oci-cloud.yaml` in -the current directory, we would run: - -```bash -juju add-cloud oci-test oci-cloud.yaml -``` +Within the 'Users' sub-menu, click on the user's email address, and then on +'Add Public Key'. Paste in the key generated earlier and click the 'Add' +button. ## Adding credentials -The [Cloud credentials][credentials] page offers a full treatment of credential +The [Credentials][credentials] page offers a full treatment of credential management. In order to access Oracle OCI, you will need to add credentials to Juju. This @@ -210,50 +142,58 @@ a ready-made controller. ### Using the interactive method Armed with the gathered information, credentials can be added interactively -with the command `juju add-credential oci-test`. However, due to the private -SSL key that needs to be provided this method is not recommended. Use the file +with the command `juju add-credential oracle`. However, due to the private SSL +key that needs to be provided this method is not recommended. Use the file method outlined next. ### Using a file A YAML-formatted file, say `mycreds.yaml`, can be used to store credential -information for any cloud. The credential file in this example would be based -on the following (replace the variables with your own values): +information for any cloud. The file in this example would be based on the +following (replace the variables with your own values): ```no-highlight credentials: - $CLOUD_NAME: + oracle: default-region: $CLOUD_REGION $CREDENTIAL_NAME: auth-type: httpsig - fingerprint: $SSL_PUBLIC_KEY_FINGERPRINT + fingerprint: $SSL_PRIVATE_KEY_FINGERPRINT key: | $SSL_PRIVATE_KEY - pass-phrase: $SSL_PRIVATE_KEY_PASSPHRASE region: $CLOUD_REGION + pass-phrase: $SSL_PRIVATE_KEY_PASSPHRASE tenancy: $OCID_TENANCY user: $OCID_USER ``` +Notes: + + - The `$SSL_PRIVATE_KEY_PASSPHRASE` value is placed within double-quotes. If the key was not encrypted just +use "". + - The `$CLOUD_REGION` is an Oracle region (`juju regions oracle`). + - The `$CREDENTIAL_NAME` is an arbitrary label. + See section [Adding credentials from a file][credentials-adding-from-file] for -guidance on what such a file looks like. +guidance on what such a file can look like. -This information is then added to Juju by pointing the `add-credential` -command to the file: +This information is then added to Juju by referencing the file with the +`add-credential` command: ```bash -juju add-credential oci-test -f mycreds.yaml +juju add-credential oracle -f mycreds.yaml ``` ## Creating a controller -You are now ready to create a Juju controller for cloud 'oci-test': +You are now ready to create a Juju controller for cloud 'oracle' (replace the +variable with your own value): ```bash -juju bootstrap --config compartment-id=$OCID_COMPARTMENT oci-test oci-test-controller +juju bootstrap --config compartment-id=$OCID_COMPARTMENT oracle oracle-controller ``` -Above, the name given to the new controller is 'oci-test-controller'. OCI +Above, the name given to the new controller is 'oracle-controller'. OCI will provision an instance to run the controller on. For a detailed explanation and examples of the `bootstrap` command see the @@ -280,8 +220,6 @@ See these pages for ideas on what to do next: [oracle-oci-tenancy]: https://docs.cloud.oracle.com/iaas/Content/GSG/Concepts/settinguptenancy.htm [oracle-oci-cli]: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdks.htm [oracle-oci-console]: https://console.us-phoenix-1.oraclecloud.com/ -[#clouds-oci-manual]: #manually-adding-an-oci-cloud -[clouds-adding-manually]: ./clouds.md#adding-clouds-manually [credentials]: ./credentials.md [jaas]: ./getting-started.md [credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file diff --git a/src/en/credentials.md b/src/en/credentials.md index 36fb24baa..8f8179aac 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -184,7 +184,7 @@ credentials: application-id: niftyapp subscription-id: 31fb132e-e774-49dd-adbb-d6a4e966c583 application-password: UberPassK3yz - oci-test: + oracle: default-region: us-ashburn-1 jlarin: auth-type: httpsig @@ -206,19 +206,19 @@ credentials: mbOkIDbK71ZG+iIfxDXLzRO1ZzPjAX3cReFZ9NFRHngX9xM92UP+icIJkM6m4ImN UcaGCZiF0LoKUTAkEw+5rpeudGcgNgaI41RKMUBLyQn5MFo3IAPaO4ECgYEAyzJN CqB4e+qJgmc29zKsSfvuofasDTmIMnOZW2ci+tiD/qiH/eJoKHK2F5yGV6/tB2iY - kFSuzWEwu/Crl8seW6xPY+HYlGLD60ix1aRDEfR48bZqFqlIu7uowI9dp43aOmPU + kFSuzWEwu/Crl7seW6xPY+HYlGLD60ix1aRDEfR48bZqFqlIu7uowI9dp43aOmPU 1YSgMj8UA+rVqHqrS6IX4iqGbEOuzq0a377qiycCgYA99oUQzsH5J1nSDxG68v3K GMr8qacMZ2+lJU7PMqZXDScCxD7Opr8pGME6SW1FciQAw36EVRWtL+BjjhBcw7TA - SM7e6wCNElO2ddLGxzQHC0N9EFMIzMZ3pK/5arMRznp0Uv2kDZOSzefo2a+gvDu/ + SM7e6wCNElO4ddLGxzQHC0N9EFMIzMZ3pK/5arMRznp0Uv2kDZOSzefo2a+gvDu/ XU9vyOtAIBft6n327TTYAQKBgEE3/OhbRzCmv8oeLNM87XW1qgtMLD72Z1OiLOfc e6q90efr2fJQOBQ7dVywvaHpco+9L7Krq4vWlXjdL4ZCCJVuAfFSLPy7kpyzMXkc - Bvb9W9BhNz3cyd6PxdDTQFhNwbXdE2QQ9IYMHvV+62LvNInLFhVehtS7CKGHiCem - lItjAoGAdnj8nJRFQCAyIGcYk6bloohXI8ko0KLYbHfQpN9oiZa+5crEMzcFiJnR + Bvb9W9BiNz3cyd6PxdDTQFhNwbXdE2QQ9IYMHvV+62LvNInLFhVehtS7CKGHiCem + lItJAoGAdnj8nJRFQCAyIGcYk6bloohXI8ko0KLYbHfQpN9oiZa+5crEMzcFiJnR X8rWVPCLZK5gJ56CnP8Iyoqah/hpxTUZoSaJnBb/xa7PCiMq1gBfSF8OYlCsRI0V semYTOymUHkZyWGMIhmdn6t1S9sOy2tYjiH6HqumwirxnD5CLDk= -----END RSA PRIVATE KEY----- - pass-phrase: "carbonbasedlifeforms" region: us-ashburn-1 + pass-phrase: "" tenancy: ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia user: ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq joyent: @@ -513,15 +513,6 @@ in that credential being related to two models. -[clouds-aws]: ./help-aws.md -[clouds-azure]: ./help-azure.md -[clouds-google]: ./help-google.md -[clouds-joyent]: ./help-joyent.md -[clouds-rackspace]: ./help-rackspace.md -[clouds-maas]: ./clouds-maas.md -[clouds-oracle]: ./help-oracle.md -[clouds-openstack]: ./help-openstack.md -[clouds-vmware]: ./help-vmware.md [yaml]: http://www.yaml.org/spec/1.2/spec.html [clouds-lxd-resources-non-admin-creds]: ./clouds-lxd-resources.md#non-admin-user-credentials [clouds-aws-using-env-variables]: ./help-aws.md#using-environment-variables diff --git a/src/en/help-oracle.md b/src/en/help-oracle.md deleted file mode 100644 index 36824074f..000000000 --- a/src/en/help-oracle.md +++ /dev/null @@ -1,279 +0,0 @@ -Title: Using Oracle Compute with Juju -TODO: Review required - -# Using Oracle Compute with Juju - -Juju has built-in support for [Oracle Compute][oracle-compute], Oracle's public -cloud. This means that there is no need to add the Oracle cloud to Juju. An -exception to this is if you have an Oracle Compute trial account. Both types of -accounts, paid and trial, are covered here. - -This page will cover the following steps: - -1. Associate Oracle's Ubuntu images with your Compute service. Juju needs these - to be able to deploy Ubuntu-based applications. -1. For trial accounts, add the Oracle cloud to Juju. -1. Add credentials to Juju so it can make use of your Oracle Compute account. -1. Create the Juju controller - -## Gathering information - -The email you received upon signing up for Oracle Compute contains vital -information you will need to complete the instructions presented here. Look -for: - -- 'My Services URL' -- 'Identity domain' -- 'My Account URL' -- 'Username' (your email address) -- 'Password' (temporary) - -Upon first login (to 'My Services URL') you will be prompted to change the -temporary password to arrive at your final password. - -## Ubuntu images - -You will need to make Ubuntu images available in your Oracle Compute account in -order for Juju to be able to create Ubuntu-based machines. This is a -requirement. - -Proceed as follows: - -1. Navigate to 'My Services URL' and log in. -1. Select your 'Identity Domain' in the top-right corner. -1. Click on the 'Create instance' box and then 'Create' a Compute service. - -![Create Compute service](./media/oracle_empty-dashboard-2.png) - -!!! Note: - We are doing this to associate images with your 'identity domain'. We will - not be creating an instance here. - -Click on 'Marketplace' on the resulting page (left menu), enter 'ubuntu' into -the search field, and hit Enter: - -![Search Ubuntu images](./media/oracle_create-instance-ubuntu-2.png) - -From the point of view of Juju, some images should not be used. -Juju-compatible images are listed below: - -| Version | Arch | Series | -|------------------| -------|---------| -| Ubuntu 12.04 LTS | amd64 | Precise | -| Ubuntu 14.04 LTS | amd64 | Trusty | -| Ubuntu 16.04 LTS | amd64 | Xenial | -| Ubuntu 17.04 | amd64 | Zesty | - -!!! Warning: - In particular, Ubuntu 16.10 (Yakkety) should not be used with Juju. - -Since Juju uses charms to install applications, the Ubuntu series you need are -those that the charms were written for. If unsure, it is recommended to add the -two most recent LTS releases. - -!!! Note: - At time of writing, Trusty and Xenial are the two most recent Ubuntu - LTS releases. - -Select a compatible image from among the official Ubuntu images (orange Ubuntu -logo), accept Oracle's terms and conditions, and click 'Install'. Repeat the -process for each desired image. These installed images will end up under -'Private Images' in the menu on the left: - -![List private images](./media/oracle_create-instance-private-2.png) - -## Trial accounts - -As mentioned, you will need to add your Oracle cloud to Juju if you're using a -trial account. This requires a 'REST Endpoint'. To get this, navigate to 'My -Account URL', scroll down to 'Oracle Compute Cloud Service', and click on it. -The resulting page will look similar to this: - -![REST endpoint](./media/oracle_myservices-endpoint-2.png) - -There may be multiple endpoints. In that case, trial and error may be needed -below (hint: the endpoint domain should be resolvable using DNS). - -You are now ready to use the interactive `add-cloud` command: - -```bash -juju add-cloud -``` - -Example user session: - -```no-highlight -Cloud Types - maas - manual - openstack - oracle - vsphere - -Select cloud type: oracle - -Enter a name for your oracle cloud: oracle-cloud - -Enter the API endpoint url for the cloud: -https://compute.uscom-central-1.oraclecloud.com/ - -Cloud "oracle-cloud" successfully added -You may bootstrap with 'juju bootstrap oracle-cloud' -``` - -We've called the new cloud 'oracle-cloud' and used an endpoint of -'https://compute.uscom-central-1.oraclecloud.com/'. - -Now confirm the successful addition of the cloud: - -```bash -juju clouds -``` - -Here is a partial output: - -```no-highlight -Cloud Regions Default Type Description -. -. -. -oracle 5 uscom-central-1 oracle Oracle Compute Cloud Service -oracle-cloud 0 oracle Oracle Compute Cloud Service -``` - -Cloud 'oracle' is for the built-in (for pay) service and cloud 'oracle-cloud' -is tied to your trial account. - -## Adding credentials - -The [Cloud credentials][credentials] page offers a full treatment of credential -management. - -Use the interactive `add-credential` command to add your credentials to your -cloud. Below, we add credentials to the trial account cloud: - -```bash -juju add-credential oracle-cloud -``` - -Here is a resulting example user session: - -```no-highlight -Enter credential name: oracle-cloud-creds - -Using auth-type "userpass". - -Enter username: javierlarin72@gmail.com - -Enter password: - -Enter identity-domain: a498151 - -Credentials added for cloud oracle-cloud. -``` - -We've called the new credential 'oracle-cloud-creds' and entered values for -'Username', 'Password', and 'Identity domain'. - -!!! Note: - The password will not be echoed back to the screen. - - -## Juju networks and spaces - -You can optionally link Oracle Compute IP networks and IP exchanges with Juju's -networks and spaces. - -To do this: - -1. Navigate to 'My Services URL'. -1. Open the left menu (top-left icon) and select 'Compute'. -1. From the 'Network' tab select 'IP Exchanges' from the menu on the left. -1. Click on the 'Create IP Exchange' button and enter a name for the exchange, - and optionally, a description and one or more tags. - -![Create an IP exchange](./media/oracle_create-ip-exchange-2.png) - -Now create a network to use this exchange by selecting 'IP Networks' from the -menu and clicking on 'Create IP Network': - -![Create an IP network](./media/oracle_create-ip-network-2.png) - -Enter a name, a CIDR formatted address for the 'IP Address Prefix', and an -optional description with one or more tags. Use the 'IP Exchange' drop-down -menu to select the exchange created previously and click on 'Create'. - -When you next create a Juju controller (see below), you'll be able to use these -new subnets and spaces. For example, typing `juju subnets` will show output -similar to the following: - -```no-highlight -subnets: - 192.168.0.0/16: - type: ipv4 - provider-id: /Compute-a498151/javierlarin72@gmail.com/oracle-cloud-ip-network - status: in-use - space: oracle-cloud-ip-exchange - zones: - - default -``` - -Typing `juju spaces` will list the exchange: - -```no-highlight -Space Subnets -oracle-cloud-ip-exchange 192.168.0.0/16 -``` - -See [How to configure more complex networks using spaces][spaces] for further -details on networks and spaces. - -## Creating a controller - -You are now ready to create a Juju controller for cloud 'oracle-cloud': - -```bash -juju bootstrap oracle-cloud oracle-cloud-controller -``` - -Above, the name given to the new controller is 'oracle-cloud-controller'. -Oracle Compute will provision an instance to run the controller on. - -Once created, you can view the controller as an Oracle Compute instance by -navigating to 'My Services URL', opening the left menu (top-left icon), and -selecting 'Compute'. The controller should be visible under the 'Instances' -tab: - -![List controller instance](./media/oracle_bootstrap-instances-2.png) - -Oracle Compute has the notion of *sites* (like availability zone or region). -You may need to change your site to see your new controller. This is done in -the top-right corner: - -![Oracle Compute sites](./media/oracle_bootstrap-instances-sites.png) - -For a detailed explanation and examples of the `bootstrap` command see the -[Creating a controller][controllers-creating] page. - -## Next steps - -A controller is created with two models - the 'controller' model, which -should be reserved for Juju's internal operations, and a model named -'default', which can be used for deploying user workloads. - -See these pages for ideas on what to do next: - - - [Juju models][models] - - [Introduction to Juju Charms][charms] - - - - -[oracle-compute]: https://cloud.oracle.com/en_US/compute -[cloudoracle]: https://cloud.oracle.com/home -[getstarted]: ./getting-started-jaas.md -[spaces]: ./network-spaces.md -[controllers-creating]: ./controllers-creating.md -[models]: ./models.md -[charms]: ./charms.md -[credentials]: ./credentials.md From 9bac8017410d37c61b8738cc785194c228be0497 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 9 Nov 2018 15:56:05 -0500 Subject: [PATCH 129/311] trivial --- src/en/clouds.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/en/clouds.md b/src/en/clouds.md index 810a56263..c2086bdc3 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -179,7 +179,6 @@ relative path to the file: Here are some examples of manually adding a cloud: - [Manually adding MAAS clouds][clouds-maas-manual] - - [Manually adding an OCI cloud][clouds-oci-manual] - [Manually adding an OpenStack cloud][clouds-openstack-manual] - [Manually adding a vSphere cloud][clouds-vsphere-manual] @@ -203,6 +202,5 @@ Here are some examples of manually adding a cloud: [controllers-creating-include-config]: ./controllers-creating.md#passing-a-cloud-specific-setting [clouds-maas-manual]: ./clouds-maas.md#manually-adding-maas-clouds -[clouds-oci-manual]: ./clouds-oci.md#manually-adding-an-oci-cloud [clouds-openstack-manual]: ./help-openstack.md#manually-adding-an-openstack-cloud [clouds-vsphere-manual]: ./help-vmware.md#manually-adding-a-vsphere-cloud From 2f750b84c5db5467cd63bd7ff4a6366830939b3c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 9 Nov 2018 15:59:07 -0500 Subject: [PATCH 130/311] trivial --- src/en/clouds-oci.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index 6ee53c25c..83d2da719 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -1,5 +1,4 @@ Title: Using Oracle OCI with Juju -TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1802577 (add '-aes128' to command that creates the key if fixed) # Using Oracle OCI with Juju From ff679306bc9aed938b992467cc3848126564fe8e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 9 Nov 2018 16:02:26 -0500 Subject: [PATCH 131/311] trivial --- src/en/charms.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/en/charms.md b/src/en/charms.md index 9239329b1..2a008e1ba 100644 --- a/src/en/charms.md +++ b/src/en/charms.md @@ -14,7 +14,6 @@ Common charm-related tasks are listed below. - [Using constraints][charms-constraints] - [Configuring applications][charms-config] - [Managing relations][charms-relations] - - [Exposing applications][charms-exposing] - [Scaling applications][charms-scaling] - [Removing things][charms-destroy] - [Upgrading applications][charms-upgrading] @@ -36,7 +35,6 @@ Common charm-related tasks are listed below. [charms-constraints]: ./charms-constraints.md [charms-config]: ./charms-config.md [charms-relations]: ./charms-relations.md -[charms-exposing]: ./charms-exposing.md [charms-scaling]: ./charms-scaling.md [charms-destroy]: ./charms-destroy.md [charms-upgrading]: ./charms-upgrading.md From 1759472de8a0e0bc8590707685a35aa1f5aad2b8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 9 Nov 2018 18:12:08 -0500 Subject: [PATCH 132/311] cloud definition; multitude of small improvments --- src/en/clouds-oci.md | 9 +++++++-- src/en/clouds.md | 24 ++++++++++++++++++++++-- src/en/controllers-creating.md | 10 ++++++++++ src/en/credentials.md | 11 +++++++---- 4 files changed, 46 insertions(+), 8 deletions(-) diff --git a/src/en/clouds-oci.md b/src/en/clouds-oci.md index 83d2da719..85a6b6725 100644 --- a/src/en/clouds-oci.md +++ b/src/en/clouds-oci.md @@ -192,8 +192,12 @@ variable with your own value): juju bootstrap --config compartment-id=$OCID_COMPARTMENT oracle oracle-controller ``` -Above, the name given to the new controller is 'oracle-controller'. OCI -will provision an instance to run the controller on. +Above, the name given to the new controller is 'oracle-controller'. OCI will +provision an instance to run the controller on. + +You can optionally change the definition of cloud 'oracle' to avoid having to +specify the compartment like this. See +[General cloud management][clouds-general-cloud-management] for how to do this. For a detailed explanation and examples of the `bootstrap` command see the [Creating a controller][controllers-creating] page. @@ -222,6 +226,7 @@ See these pages for ideas on what to do next: [credentials]: ./credentials.md [jaas]: ./getting-started.md [credentials-adding-from-file]: ./credentials.md#adding-credentials-from-a-file +[clouds-general-cloud-management]: ./clouds.md#general-cloud-management [controllers-creating]: ./controllers-creating.md [models]: ./models.md [charms]: ./charms.md diff --git a/src/en/clouds.md b/src/en/clouds.md index c2086bdc3..5fcf426e6 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -122,6 +122,26 @@ cloud): juju update-clouds ``` +To change the definition of an existing cloud, 'oracle' for instance, create a +[YAML-formatted][yaml] file, say `oracle.yaml`, with contents like: + +```no-highlight +clouds: + oracle: + type: oci + config: + compartment-id: +``` + +And then: + +```bash +juju add-cloud --replace oracle oracle.yaml +``` + +This will avoid you having to include `--config compartment-id=` at +controller-creation time (`bootstrap`). + ## Adding clouds Adding a cloud is done with the `add-cloud` command, which has both interactive @@ -144,8 +164,8 @@ configuration file. It has the following format: ```yaml clouds: : - type: - auth-types: [] + type: + auth-types: [] regions: : endpoint: diff --git a/src/en/controllers-creating.md b/src/en/controllers-creating.md index e218ef91e..45e98eded 100644 --- a/src/en/controllers-creating.md +++ b/src/en/controllers-creating.md @@ -1,5 +1,6 @@ Title: Creating a controller TODO: Hardcoded: Ubuntu code names + Remove gerunds from example listings (fix links from other pages) # Creating a controller @@ -34,6 +35,7 @@ be done at controller-creation time: - [Placing a controller on a specific MAAS node][#placing-a-controller-on-a-specific-maas-node] - [Specifying an agent version][#specifying-an-agent-version] - [Passing a cloud-specific setting][#passing-a-cloud-specific-setting] + - [Include configuration options at the cloud level][#include-configuration-options-at-the-cloud-level] ### Create a controller interactively @@ -225,6 +227,12 @@ juju boootstrap --config vpc-id=vpc-86f7bbe1 aws Cloud-specific features can also be passed to individual models during their creation (`add-model`). +### Include configuration options at the cloud level + +Any settings passed via the `--config` option can be included in the definition +of a cloud. See [General cloud management][clouds-general-cloud-management] for +how to do this. + @@ -233,6 +241,7 @@ juju boootstrap --config vpc-id=vpc-86f7bbe1 aws [models-config]: ./models-config.md [troubleshooting-logs-remote]: ./troubleshooting-logs-remote.md [agent-versions-and-streams]: ./models-config.md#agent-versions-and-streams +[clouds-general-cloud-management]: ./clouds.md#general-cloud-management [#create-a-controller-interactively]: #create-a-controller-interactively [#set-default-model-constraints-for-a-controller]: #set-default-model-constraints-for-a-controller @@ -247,3 +256,4 @@ juju boootstrap --config vpc-id=vpc-86f7bbe1 aws [#placing-a-controller-on-a-specific-maas-node]: #placing-a-controller-on-a-specific-maas-node [#specifying-an-agent-version]: #specifying-an-agent-version [#passing-a-cloud-specific-setting]: #passing-a-cloud-specific-setting +[#include-configuration-options-at-the-cloud-level]: #include-configuration-options-at-the-cloud-level diff --git a/src/en/credentials.md b/src/en/credentials.md index 8f8179aac..54bd990ea 100644 --- a/src/en/credentials.md +++ b/src/en/credentials.md @@ -191,17 +191,20 @@ credentials: fingerprint: a3:57:81:9c:d2:d5:af:31:3b:73:1e:2b:a4:ae:96:ee key: | -----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED + DEK-Info: AES-128-CBC,AAAC919B21A2694027DBEB182593FBEC + MIIEogIBAAKCAQEAoc9jtcvo49FWe3sOhS6c1ExkllNZ61vChsLmMhBCI1vMc8wu cMpNmYK1ZA+d2Mm5YWDwn4UrSTzyaFdAIesmRljfbYMGTLznI/nfQMa1hkmplF5Q xNPCdzs0afqfnubIyrvCKYfAsRzjCcs7C30n6PzG5WrKxzr1QNvAuvYgjd2oQuSY - nAhDgdJDkA9UwJFgI1hE8EuoxjkvmyeL76ohe78IEjMzoBBvll/Vd3d8X/hCHt4b - wkmn3B5+QzXIvYXGhaUoZrmG6V+tek2H5voJj6TswDB8rqIa1SHbY81wIkMUxbD4 + nAhDgdJDkA9UwJFgI1jE8EuoxjkvmyeL76ohe78IEjMzoBBvll/Vd3d8X/hCHt4b + wkmn3B5+QzXIvYXGhaUoZrmG6V+tsk2H5voJj6TswDB8rqIa1SHbY81wIkMUxbD4 ScAq8eq2/6ETXcoBULKCjmvyqekJHjT7NngbpwIDAQABAoIBAEEggheIDSK0/UQS EZQVYNYqMUo4HjcW5cL/PRvlY1lr92ycQAzxwC4LaArwJi49czn4lKEALp35w++v PoboaK1j0/n2BLEaT0YxqmQeFq4INBMdqxCt0tW+pKgLUffZF/RRgiLJGwuufstQ W2GSbF/gbgWk6B0sY85JJNebfRrb+qjp5Jz+5t5gNVzOwWWkPYoAKXPd9JHYPFAk JCUTloYdf16lBml+nZI7EGojXtHUpdF7KyYRVfXMfxBnaWpVHvoZBk5Vk5qL/boz - N8W+YahFq9BELavYQ30CZQeWYoD2MUSCWv+WzfkER8YK5Onr+5CSU0lW9dqN6wuv + N8W+YahFq9BELavYQ30CZQeWYoD2MaSCWv+WzfkER8YK5Onr+5CSU0lW9dqN6wuv LFozUgECgYEAy9vZb+hjn3otkEFvyCGg9wmGIs9Qro3UKJI/mGKQeL7K8sd5WsA6 mbOkIDbK71ZG+iIfxDXLzRO1ZzPjAX3cReFZ9NFRHngX9xM92UP+icIJkM6m4ImN UcaGCZiF0LoKUTAkEw+5rpeudGcgNgaI41RKMUBLyQn5MFo3IAPaO4ECgYEAyzJN @@ -218,7 +221,7 @@ credentials: semYTOymUHkZyWGMIhmdn6t1S9sOy2tYjiH6HqumwirxnD5CLDk= -----END RSA PRIVATE KEY----- region: us-ashburn-1 - pass-phrase: "" + pass-phrase: "ChimayBlue" tenancy: ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia user: ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq joyent: From 514b53b56914427a0acec2c8e5a58326ceef0b16 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 12 Nov 2018 20:58:06 -0500 Subject: [PATCH 133/311] storage --- src/en/clouds-k8s.md | 149 +++++++++++++++++++++++++++++++------------ 1 file changed, 108 insertions(+), 41 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 137234c57..c34b7423e 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -3,7 +3,8 @@ TODO: Should eventually link to k8s-charm developer documentation Update when storage becomes a Juju drivable aspect. Add architectural overview/diagram once Juju:k8s becomes stable. Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` - Add charms section when they become available in the charm store + Add charms section when they become available in the charm store (change from staging store to production store) + Link to Discourse posts for microk8s, aws-integrator? # Using Kubernetes with Juju @@ -53,53 +54,68 @@ To summarise, the steps for using Kubernetes with Juju are: ### Obtain a Kubernetes cluster You may obtain a Kubernetes cluster in any way. However, in this document, we -deploy the cluster using Juju itself (with the localhost cloud). We will do so -by deploying a minimal two-machine Kubernetes cluster by making use of the +deploy the cluster using Juju itself (with the 'localhost' cloud). We will do +so by deploying a minimal two-machine Kubernetes cluster by making use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash -juju bootstrap localhost lxd-k8s +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd-k8s juju deploy kubernetes-core ``` -!!! Note: - An alternative to using the bundle is to use the `conjure-up` installer. - See Ubuntu tutorial - [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] - for guidance. Although the tutorial specifically mentions the - [Canonical Distribution of Kubernetes][cdk-charm] you can choose the - identical minimal install deployed above from the installer's interface. - -Sample output looks like this: +Sample output to `juju status` looks like this: ```no-highlight -Model Controller Cloud/Region Version SLA -default lxd localhost/localhost 2.4-beta3 unsupported +Model Controller Cloud/Region Version SLA Timestamp +default lxd-k8s localhost/localhost 2.5-beta1 unsupported 17:38:29Z App Version Status Scale Charm Store Rev OS Notes -easyrsa 3.0.1 active 1 easyrsa jujucharms 40 ubuntu -etcd 3.2.9 active 1 etcd jujucharms 80 ubuntu -flannel 0.9.1 active 2 flannel jujucharms 56 ubuntu -kubernetes-master 1.10.2 waiting 1 kubernetes-master jujucharms 104 ubuntu exposed -kubernetes-worker 1.10.2 active 1 kubernetes-worker jujucharms 118 ubuntu exposed - -Unit Workload Agent Machine Public address Ports Message -easyrsa/0* active idle 0/lxd/0 10.0.219.187 Certificate Authority connected. -etcd/0* active idle 0 10.191.96.169 2379/tcp Healthy with 1 known peer -kubernetes-master/0* waiting executing 0 10.191.96.169 6443/tcp (config-changed) Waiting for kube-system pods to start - flannel/0* active idle 10.191.96.169 Flannel subnet 10.1.21.1/24 -kubernetes-worker/0* active executing 1 10.191.96.126 80/tcp,443/tcp (config-changed) Kubernetes worker running. - flannel/1 active idle 10.191.96.126 Flannel subnet 10.1.69.1/24 - -Machine State DNS Inst id Series AZ Message -0 started 10.191.96.169 juju-c841ac-0 xenial Running -0/lxd/0 started 10.0.219.187 juju-c841ac-0-lxd-0 xenial Container started -1 started 10.191.96.126 juju-c841ac-1 xenial Running - -Controller Timestamp -23 May 2018 14:00:52Z +easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu +etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu +flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu +kubernetes-master 1.12.2 waiting 1 kubernetes-master jujucharms 219 ubuntu exposed +kubernetes-worker 1.12.2 active 1 kubernetes-worker jujucharms 239 ubuntu exposed + +Unit Workload Agent Machine Public address Ports Message +easyrsa/0* active idle 0/lxd/0 10.232.236.186 Certificate Authority connected. +etcd/0* active idle 0 10.80.187.237 2379/tcp Healthy with 1 known peer +kubernetes-master/0* waiting idle 0 10.80.187.237 6443/tcp Waiting for kube-system pods to start + flannel/0* active idle 10.80.187.237 Flannel subnet 10.1.24.1/24 +kubernetes-worker/0* active idle 1 10.80.187.177 80/tcp,443/tcp Kubernetes worker running. + flannel/1 active idle 10.80.187.177 Flannel subnet 10.1.34.1/24 + +Machine State DNS Inst id Series AZ Message +0 started 10.80.187.237 juju-2ad61f-0 bionic Running +0/lxd/0 started 10.232.236.186 juju-2ad61f-0-lxd-0 bionic Container started +1 started 10.80.187.177 juju-2ad61f-1 bionic Running ``` +!!! Note: + We've used the staging Charm Store in these instructions as the standard + site does not yet contain the Kubernetes charms and bundles. + +**Alternative methods for obtaining a Kubernetes cluster** +Beyond your own custom/bespoke Kubernetes cluster, here is a list of +alternative methods to explore for setting one up: + + 1. Use the 'canonical-kubernetes' bundle, which is a more sophisticated + version of what we used above. + 1. Use the [`conjure-up`][upstream-conjure-up] installer. See Ubuntu tutorial + [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] + for guidance. Although the tutorial specifically mentions the + [Canonical Distribution of Kubernetes][cdk-charm] you can choose the + identical minimal install deployed above from the installer's interface. + 1. Use [`microk8s`][upstream-microk8s]. With microk8s, you get a local, fully + compliant Kubernetes deployment with dynamic persistent volume support, and + a running ingres controller. + 1. Use a bundle made for the major cloud vendors. There are special + "integrator" charms that assist with such deployments. + [Search the Charm Store][charm-store-integrator] for 'integrator'. + 1. Use a public cloud vendor such as [Amazon EKS][upstream-eks-kubernetes], + [Azure AKS][upstream-aks-kubernetes], + [Google GKE][upstream-gke-kubernetes], and + [DigitalOcean Kubernetes][upstream-dok-kubernetes]. + ### Add the cluster to Juju We will need some information about the cluster in order to add it to Juju. @@ -109,7 +125,7 @@ This is found within the main Kubernetes configuration file. If `conjure-up` was used to install the cluster then the rest of this section can be skipped; this install method adds the cluster for you. -#### Adding quickly (bundle installs) +#### Adding a juju-deployed cluster quickly If the `juju deploy` command was used to deploy the cluster the above file can be copied over from the Kubernetes master node (and saved as `~/.kube/config`) @@ -122,10 +138,10 @@ juju scp kubernetes-master/0:config ~/.kube/config We can now take advantage of the `add-k8s` command as it internally parses the copied configuration file from the specified path. This allows us to quickly -add the cluster-cloud, which we have arbitrarily called 'k8scloud': +add the cluster-cloud, which we have arbitrarily called 'lxd-k8s-cloud': ```bash -juju add-k8s k8scloud +juju add-k8s lxd-k8s-cloud ``` Now confirm the successful addition of the cloud: @@ -149,12 +165,55 @@ k8scloud 0 kubernetes Add a model in the usual way: ```bash -juju add-model k8smodel +juju add-model lxd-k8s-model lxd-k8s-cloud ``` This will cause a Kubernetes namespace in the cluster to be created that will host all of the pods and other resources for that model. +## Juju and Kubernetes storage + +For each Juju-deployed Kubernetes application an *operator pod* is +automatically set up whose task it is to run the charm hooks for each deployed +unit’s charm. + +Each charm requires persistent storage so that things like state and resources +can be preserved if the pod ever restarts. To accomplish this, a Juju storage +pool called 'operator-storage' with the provider type 'kubernetes' must exist. + +### Operator storage + +Operator storage is set up by defining a Juju storage pool that maps to a +Kubernetes storage class. Below are some examples using various Kubernetes +storage provisioners: + +For AWS using EBS volumes: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=juju-operator-storage \ + storage-provisioner=kubernetes.io/aws-ebs \ + parameters.type=gp2 +``` + +For GKE using Persistent Disk: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=juju-operator-storage \ + storage-provisioner=kubernetes.io/gce-pd \ + parameters.type=pd-standard +``` + +For `microk8s` using built-in hostPath storage: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=microk8s-hostpath +``` + +### Charm storage + ## Configuration Juju k8s applications support application specific configuration. This allows @@ -197,5 +256,13 @@ Kubernetes `scale` command. [kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ -[upstream-kubernetes-docs]: https://kubernetes.io/docs [credentials]: ./credentials.md +[upstream-kubernetes-docs]: https://kubernetes.io/docs +[upstream-microk8s]: https://microk8s.io +[upstream-conjure-up]: https://conjure-up.io/ +[charm-store-integrator]: https://staging.jujucharms.com/q/integrator + +[upstream-eks-kubernetes]: https://aws.amazon.com/eks/ +[upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ +[upstream-gke-kubernetes]: https://cloud.google.com/kubernetes-engine/ +[upstream-dok-kubernetes]: https://www.digitalocean.com/products/kubernetes/ From 5dbc98137bd4fdc6b01e215803e189ff63d5c403 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 14 Nov 2018 08:46:00 -0500 Subject: [PATCH 134/311] details --- src/en/clouds-k8s.md | 73 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 13 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index c34b7423e..1b50566e2 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -1,10 +1,11 @@ Title: Using Kubernetes with Juju TODO: Should eventually link to k8s-charm developer documentation Update when storage becomes a Juju drivable aspect. - Add architectural overview/diagram once Juju:k8s becomes stable. + Add architectural overview/diagram Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` Add charms section when they become available in the charm store (change from staging store to production store) Link to Discourse posts for microk8s, aws-integrator? + Write a tutorial or two on building a cluster using the methods listed # Using Kubernetes with Juju @@ -13,9 +14,6 @@ applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. -!!! Note: - Kubernetes is often abbreviated as "k8s" (pronounced "kate's"). - ## Juju k8s-specific workflow The only k8s-specific Juju commands are `add-k8s` and `remove-k8s`. All other @@ -110,7 +108,7 @@ alternative methods to explore for setting one up: a running ingres controller. 1. Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. - [Search the Charm Store][charm-store-integrator] for 'integrator'. + [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. 1. Use a public cloud vendor such as [Amazon EKS][upstream-eks-kubernetes], [Azure AKS][upstream-aks-kubernetes], [Google GKE][upstream-gke-kubernetes], and @@ -153,11 +151,11 @@ juju clouds Here is a partial output: ```no-highlight -Cloud Regions Default Type Description +Cloud Regions Default Type Description . . . -k8scloud 0 kubernetes +lxd-k8s-cloud 0 kubernetes ``` ## Add a model @@ -175,17 +173,20 @@ host all of the pods and other resources for that model. For each Juju-deployed Kubernetes application an *operator pod* is automatically set up whose task it is to run the charm hooks for each deployed -unit’s charm. +unit's charm. Each charm requires persistent storage so that things like state and resources -can be preserved if the pod ever restarts. To accomplish this, a Juju storage -pool called 'operator-storage' with the provider type 'kubernetes' must exist. +can be preserved if the operator pod ever restarts. To accomplish this, a Juju +storage pool called 'operator-storage' with provider type 'kubernetes' must +exist. + +Charm storage........................... ### Operator storage Operator storage is set up by defining a Juju storage pool that maps to a -Kubernetes storage class. Below are some examples using various Kubernetes -storage provisioners: +Kubernetes storage class. Here are examples of definitions that use various +Kubernetes storage provisioners: For AWS using EBS volumes: @@ -212,8 +213,53 @@ juju create-storage-pool operator-storage kubernetes \ storage-class=microk8s-hostpath ``` +Although the recommended approach is to use Juju-defined storage, Juju does +support externally created storage. Juju will use this order of precedence in +determining which storage it will use: + + 1. storage class called 'juju-operator-storage' + 1. storage class with label 'juju-storage', one of: + '-operator-storage' + '' + 'default' + 1. storage class called 'storageclass.kubernetes.io/is-default-class' + ### Charm storage +Kubernetes charms requiring persistent storage can make use of Kubernetes +persistent volumes. Currently, only filesystem storage is supported. + +As with standard charms, storage requirements are stated in the Kubernetes charm's +`metadata.yaml` file: + +```no-highlight +storage: + database: + type: filesystem + location: /var/lib/mysql +``` + +An example is the [mariadb-k8s][staging-mariadb-k8s] charm. + +There are two ways to configure the Kubernetes cluster to provide persistent +storage: + + - A pool of manually provisioned, static persistent volumes + - Using a storage class for dynamic provisioning of volumes + +In both cases, a Juju storage pool is created and, if needed, can be configured +with Kubernetes-specific settings. + +Like for operator storage, Juju supports externally created storage and will +use very similar rules for determining which storage it will use: + + 1. storage class called 'juju-unit-storage' + 1. storage class with label 'juju-storage', one of: + '-unit-storage' + '' + 'default' + 1. storage class called 'storageclass.kubernetes.io/is-default-class' + ## Configuration Juju k8s applications support application specific configuration. This allows @@ -260,7 +306,8 @@ Kubernetes `scale` command. [upstream-kubernetes-docs]: https://kubernetes.io/docs [upstream-microk8s]: https://microk8s.io [upstream-conjure-up]: https://conjure-up.io/ -[charm-store-integrator]: https://staging.jujucharms.com/q/integrator +[charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator +[charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ From 69ba8589445f50966ef23151e983c3f3bee945fc Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 14 Nov 2018 08:52:09 -0500 Subject: [PATCH 135/311] fix link --- src/en/network-spaces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/network-spaces.md b/src/en/network-spaces.md index 0975f14bc..912b71527 100644 --- a/src/en/network-spaces.md +++ b/src/en/network-spaces.md @@ -123,8 +123,8 @@ upon using either a *constraint* or a *binding*: - See the [Using constraints][charms-constraints] page to learn more about constraints. - For examples of using the 'spaces' constraint, read - [Deploying to spaces][deploying-to-spaces] for how to use it with the - `deploy` command and + [Deploying to spaces][deploying-to-network-spaces] for how to use it + with the `deploy` command and [Setting constraints when adding a machine][charms-constraints-add-machine] for how to use it with the `add-machine` command. From 0f23ccc863d8fa935abe98fb1785c2177463cdeb Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 14 Nov 2018 10:05:46 -0500 Subject: [PATCH 136/311] add new status; minor drive-by --- src/en/upgrade-series.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 59f7e6c66..1e379a6cd 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -24,7 +24,8 @@ using an alternate method. Here is an overview of the process: 1. The user initiates the upgrade. - 1. The machine is no longer available for charm deployments. + 1. The machine is no longer available for charm deployments or for hosting + new containers. 1. Juju prepares the machine for the upcoming OS upgrade. 1. All units on the machine are taken into account. 1. The user manually performs the upgrade of the operating system and makes @@ -75,6 +76,14 @@ The deployed charms will be inspected for a 'pre-series-upgrade' hook. If such a hook exists, it will be run. In our example, such a hook was not found in the charm. +A machine in "prepare mode" will be noted as such in the output to the `status` +(or `machines`) command: + +```no-highlight +Machine State DNS Inst id Series AZ Message +1 started 10.116.98.194 juju-573842-0 xenial Series upgrade: prepare completed +``` + ### Upgrading the operating system One important step in upgrading the operating system is the upgrade of all From 3a3f437cb48914a89b13cba2b259a7300107bfe0 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 14 Nov 2018 22:22:41 -0500 Subject: [PATCH 137/311] ongoing --- src/en/clouds-k8s.md | 158 +++++++++++++++++++++++++++++++++---------- 1 file changed, 121 insertions(+), 37 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 1b50566e2..7ca0029e7 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -6,6 +6,7 @@ TODO: Should eventually link to k8s-charm developer documentation Add charms section when they become available in the charm store (change from staging store to production store) Link to Discourse posts for microk8s, aws-integrator? Write a tutorial or two on building a cluster using the methods listed + Add how to create external storage # Using Kubernetes with Juju @@ -171,17 +172,116 @@ host all of the pods and other resources for that model. ## Juju and Kubernetes storage -For each Juju-deployed Kubernetes application an *operator pod* is -automatically set up whose task it is to run the charm hooks for each deployed -unit's charm. +For each Juju-deployed Kubernetes application an *operator pod* is set up +automatically whose task it is to run the charm hooks for each unit. -Each charm requires persistent storage so that things like state and resources -can be preserved if the operator pod ever restarts. To accomplish this, a Juju -storage pool called 'operator-storage' with provider type 'kubernetes' must -exist. +Each charm also requires persistent storage so that things like state and +resources can be preserved if the operator pod ever restarts. To accomplish +this, a Juju storage pool called 'operator-storage' with provider type +'kubernetes' is required. Charm storage........................... +Both types of storage can be either Juju-managed or managed externally to Juju +(i.e. within Kubernetes itself). Furthermore, Juju-managed storage can be +provisioned either dynamically or statically. + +### Juju-managed storage + +There are two types of persistent storage that Juju can manage: + + - dynamically provisioned volumes + - statically provisioned volumes + +In both cases, a Juju storage pool is created by the Juju operator. The second +type is needed when the storage system for your chosen backing cloud is not +supported by Kubernetes. This situation therefore demands that volumes be set +up prior to the creation of the storage pool. See +[Types of persistent volumes][upstream-kubernetes-volumes] for the list of +Kubernetes supported backends. + +To define static volumes the below procedure can be used. YAML-formatted files +`lxd-op1.yaml` and `lxd-vol1.yaml` define operator storage and charm storage +respectively. Notice how these files allude to LXD, which is a backing cloud +that is not supported by Kubernetes. + +```bash +sudo snap install --classic kubectl +sudo mkdir -p /mnt/data/{op1,vol1} +kubectl create -f lxd-k8s-model-op1.yaml +kubectl create -f lxd-k8s-model-vol1.yaml +kubectl describe pv +``` + +!!! Important: + The storage classes that will subsequently be created must have names that + are prefixed with the name of the model in use. We've included the model + name of 'lxd-k8s-model' in various places to emphasise the importance of + the model. + +The content of the storage definition files are given below. Typically multiple +charm storage volumes would be required. + +^# lxd-k8s-model-op1.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: op1 + spec: + capacity: + storage: 1032Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: lxd-k8s-model-operator-storage + hostPath: + path: "/mnt/data/op1" + +^# lxd-k8s-model-vol1.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: vol1 + spec: + capacity: + storage: 100Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: lxd-k8s-model-charm-storage + hostPath: + path: "/mnt/data/vol1" + +Note that operator storage needs a minimum of 1024 MiB. + +### External storage + +Although the recommended approach is to use Juju-managed storage, Juju does +support externally created storage for both operator storage and charm storage. + +For operator storage, Juju will use this order of precedence for determining +the storage it will use: + + 1. a storage class called `juju-operator-storage` + 1. a storage class with label `juju-storage`, and one of these labels: + 1. `-operator-storage` + 1. `` + 1. `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +For charm storage the rules are similar: + + 1. a storage class called `juju-unit-storage` + 1. a storage class with label `juju-storage`, and one of these labels: + 1. `-unit-storage` + 1. `` + 1. `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +This documentation will focus on Juju-managed storage only. + ### Operator storage Operator storage is set up by defining a Juju storage pool that maps to a @@ -213,24 +313,26 @@ juju create-storage-pool operator-storage kubernetes \ storage-class=microk8s-hostpath ``` -Although the recommended approach is to use Juju-defined storage, Juju does -support externally created storage. Juju will use this order of precedence in -determining which storage it will use: +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=lxd-op-storage \ + storage-provisioner=kubernetes.io/no-provisioner +``` + +```bash +juju create-storage-pool lxd-k8s-pool kubernetes \ + storage-class=lxd-model-charm-storage \ + storage-provisioner=kubernetes.io/no-provisioner +``` - 1. storage class called 'juju-operator-storage' - 1. storage class with label 'juju-storage', one of: - '-operator-storage' - '' - 'default' - 1. storage class called 'storageclass.kubernetes.io/is-default-class' ### Charm storage Kubernetes charms requiring persistent storage can make use of Kubernetes persistent volumes. Currently, only filesystem storage is supported. -As with standard charms, storage requirements are stated in the Kubernetes charm's -`metadata.yaml` file: +As with standard charms, storage requirements are stated in the Kubernetes +charm's `metadata.yaml` file: ```no-highlight storage: @@ -241,25 +343,6 @@ storage: An example is the [mariadb-k8s][staging-mariadb-k8s] charm. -There are two ways to configure the Kubernetes cluster to provide persistent -storage: - - - A pool of manually provisioned, static persistent volumes - - Using a storage class for dynamic provisioning of volumes - -In both cases, a Juju storage pool is created and, if needed, can be configured -with Kubernetes-specific settings. - -Like for operator storage, Juju supports externally created storage and will -use very similar rules for determining which storage it will use: - - 1. storage class called 'juju-unit-storage' - 1. storage class with label 'juju-storage', one of: - '-unit-storage' - '' - 'default' - 1. storage class called 'storageclass.kubernetes.io/is-default-class' - ## Configuration Juju k8s applications support application specific configuration. This allows @@ -304,6 +387,7 @@ Kubernetes `scale` command. [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [credentials]: ./credentials.md [upstream-kubernetes-docs]: https://kubernetes.io/docs +[upstream-kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes [upstream-microk8s]: https://microk8s.io [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator From a37997b36a59dd332913c47c2074699d7eee2e49 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 15 Nov 2018 14:07:54 -0500 Subject: [PATCH 138/311] add page; refactor --- src/en/charms-storage-k8s.md | 199 +++++++++++++++++++++++++++++++++++ src/en/charms-storage.md | 8 +- src/en/clouds-k8s.md | 187 ++------------------------------ 3 files changed, 213 insertions(+), 181 deletions(-) create mode 100644 src/en/charms-storage-k8s.md diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md new file mode 100644 index 000000000..1a62d2378 --- /dev/null +++ b/src/en/charms-storage-k8s.md @@ -0,0 +1,199 @@ +Title: Persistent storage and Kubernetes +TODO: Add how to create external storage + Write a tutorial or two on using storage + +# Persistent storage and Kubernetes + +For each Juju-deployed Kubernetes application an *operator pod* is set up +automatically whose task it is to run the charm hooks for each unit. Each charm +also requires such persistent storage so that things like state and resources +can be preserved if the operator pod ever restarts. To accomplish all this, a +Juju storage pool called 'operator-storage' with provider type 'kubernetes' is +required. We call this type of storage *operator storage*. + +In addition, a Kubernetes charm may itself require persistent storage (e.g. +the [mariadb-k8s][charm-store-staging-mariadb-k8s] charm). Its Juju storage +pool also has a provider type of 'kubernetes'. We call this type of +storage *charm storage*. As with standard charms, storage requirements are +stated in the charm's `metadata.yaml` file: + +```no-highlight +storage: + database: + type: filesystem + location: /var/lib/mysql +``` + + + +Both operator storage and charm storage can be either Juju-managed or managed +externally to Juju (i.e. within Kubernetes itself). Furthermore, Juju-managed +storage can be provisioned either dynamically or statically. + +!!! Note: + The topic of storage is covered in a non-Kubernetes context on the + [Using Juju Storage][charms-storage] page. + +### Juju-managed storage + +There are two types of persistent storage that Juju can manage: + + - dynamically provisioned volumes + - statically provisioned volumes + +In both cases, a Juju storage pool needs to be created by the Juju operator. +The second type is needed when the storage system for your chosen backing cloud +is not supported by Kubernetes. This situation therefore demands that volumes +be set up prior to the creation of the storage pool. See +[Types of persistent volumes][upstream-kubernetes-volumes] for the list of +Kubernetes supported backends. + +To define static volumes the below procedure is provided that caters +specifically to the ongoing example used on this page. The example +YAML-formatted files `lxd-op1.yaml` and `lxd-vol1.yaml` define operator storage +and charm storage respectively. Notice how these files allude to LXD, which is +a backing cloud that is not natively supported by Kubernetes. + +```bash +sudo snap install --classic kubectl +sudo mkdir -p /mnt/data/{op1,vol1} +kubectl create -f lxd-k8s-model-op1.yaml +kubectl create -f lxd-k8s-model-vol1.yaml +kubectl describe pv +``` + +!!! Important: + The storage classes that will subsequently be created must have names that + are prefixed with the name of the model in use. We've included the model + name of 'lxd-k8s-model' in various places to emphasise the importance of + the model. + +The content of the storage definition files are given below. Typically multiple +charm storage volumes would be required. Note that operator storage needs a +minimum of 1024 MiB. + +^# lxd-k8s-model-op1.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: op1 + spec: + capacity: + storage: 1032Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: lxd-k8s-model-operator-storage + hostPath: + path: "/mnt/data/op1" + +^# lxd-k8s-model-vol1.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: vol1 + spec: + capacity: + storage: 100Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: lxd-k8s-model-charm-storage + hostPath: + path: "/mnt/data/vol1" + +We will show how to create Juju storage pools using our newly-defined storage +classes in section [Creating storage pools][#creating-storage-pools]. + +### External storage + +Although the recommended approach is to use Juju-managed storage, Juju does +support externally created storage for both operator storage and charm storage. + +For operator storage, Juju will use this order of precedence for determining +the storage it will use: + + 1. a storage class called `juju-operator-storage` + 1. a storage class with label `juju-storage`, and one of these labels: + 1. `-operator-storage` + 1. `` + 1. `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +For charm storage the rules are similar: + + 1. a storage class called `juju-unit-storage` + 1. a storage class with label `juju-storage`, and one of these labels: + 1. `-unit-storage` + 1. `` + 1. `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +This documentation will focus on Juju-managed storage only. + +### Creating storage pools + +Juju storage pools are created for both operator storage and charm storage +using the `create-storage-pool` command. Both are done by mapping to either a +Kubernetes storage class (dynamically provisioned volumes) or to a manually +defined one (statically provisioned volumes). Examples are provided below. + +These examples create a Juju storage pool called 'operator-storage' with a +provider type of 'kubernetes'. + +For AWS using EBS volumes: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=juju-operator-storage \ + storage-provisioner=kubernetes.io/aws-ebs \ + parameters.type=gp2 +``` + +For GKE using Persistent Disk: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=juju-operator-storage \ + storage-provisioner=kubernetes.io/gce-pd \ + parameters.type=pd-standard +``` + +For `microk8s` using built-in hostPath storage: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=microk8s-hostpath +``` + +For a manually defined storage class called 'lxd-k8s-model-operator-storage': + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=lxd-k8s-model-operator-storage \ + storage-provisioner=kubernetes.io/no-provisioner +``` + +Creating a charm storage pool is done very similarly. The below example creates +a pool called 'lxd-k8s-pool' using a manually defined storage class called +'lxd-k8s-model-charm-storage': + +```bash +juju create-storage-pool lxd-k8s-pool kubernetes \ + storage-class=lxd-k8s-model-charm-storage \ + storage-provisioner=kubernetes.io/no-provisioner +``` + + + + +[charms-storage]: ./charms-storage.md +[upstream-kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes +[#creating-storage-pools]: #creating-storage-pools +[charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 diff --git a/src/en/charms-storage.md b/src/en/charms-storage.md index 28122708f..acb973948 100644 --- a/src/en/charms-storage.md +++ b/src/en/charms-storage.md @@ -1,9 +1,9 @@ -Title: Using Juju Storage +Title: Using Juju storage TODO: bug tracking: https://pad.lv/1708212 bug tracking: https://pad.lv/1709507 bug tracking: https://pad.lv/1709508 -# Using Juju Storage +# Using Juju storage Certain applications can benefit from advanced storage configurations and if a charm exists for such an application Juju can declare such requirements both @@ -18,6 +18,9 @@ to the [PostgreSQL charm][charm-store-postgresql] and the The Ceph examples used here are based on the Ceph cluster described in the document [Installing Ceph][charms-storage-ceph]. +Using storage with Kubernetes is covered in +[Persistent storage and Kubernetes][charms-storage-k8]. + ## Storage management commands Outside of application deployment, Juju also has a wide array of storage @@ -613,6 +616,7 @@ For guidance on how to create a charm that uses these storage features see [clouds-lxd]: ./clouds-LXD.md [charms-storage-ceph]: ./charms-storage-ceph.html +[charms-storage-k8]: ./charms-storage-k8s.md [generic-storage-loop]: https://en.wikipedia.org/wiki/Loop_device [generic-storage-rootfs]: https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt [generic-storage-tmpfs]: https://en.wikipedia.org/wiki/Tmpfs diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 7ca0029e7..1f7971f8c 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -6,7 +6,6 @@ TODO: Should eventually link to k8s-charm developer documentation Add charms section when they become available in the charm store (change from staging store to production store) Link to Discourse posts for microk8s, aws-integrator? Write a tutorial or two on building a cluster using the methods listed - Add how to create external storage # Using Kubernetes with Juju @@ -47,7 +46,9 @@ To summarise, the steps for using Kubernetes with Juju are: 1. Obtain a Kubernetes cluster 1. Add the cluster to Juju - 1. Create a controller (and optionally a model) + 1. Add a model + 1. Define storage classes (if necessary) + 1. Create storage pools 1. Deploy k8s-specific charms ### Obtain a Kubernetes cluster @@ -159,7 +160,7 @@ Cloud Regions Default Type Description lxd-k8s-cloud 0 kubernetes ``` -## Add a model +### Add a model Add a model in the usual way: @@ -170,178 +171,9 @@ juju add-model lxd-k8s-model lxd-k8s-cloud This will cause a Kubernetes namespace in the cluster to be created that will host all of the pods and other resources for that model. -## Juju and Kubernetes storage - -For each Juju-deployed Kubernetes application an *operator pod* is set up -automatically whose task it is to run the charm hooks for each unit. - -Each charm also requires persistent storage so that things like state and -resources can be preserved if the operator pod ever restarts. To accomplish -this, a Juju storage pool called 'operator-storage' with provider type -'kubernetes' is required. - -Charm storage........................... - -Both types of storage can be either Juju-managed or managed externally to Juju -(i.e. within Kubernetes itself). Furthermore, Juju-managed storage can be -provisioned either dynamically or statically. - -### Juju-managed storage - -There are two types of persistent storage that Juju can manage: - - - dynamically provisioned volumes - - statically provisioned volumes - -In both cases, a Juju storage pool is created by the Juju operator. The second -type is needed when the storage system for your chosen backing cloud is not -supported by Kubernetes. This situation therefore demands that volumes be set -up prior to the creation of the storage pool. See -[Types of persistent volumes][upstream-kubernetes-volumes] for the list of -Kubernetes supported backends. - -To define static volumes the below procedure can be used. YAML-formatted files -`lxd-op1.yaml` and `lxd-vol1.yaml` define operator storage and charm storage -respectively. Notice how these files allude to LXD, which is a backing cloud -that is not supported by Kubernetes. - -```bash -sudo snap install --classic kubectl -sudo mkdir -p /mnt/data/{op1,vol1} -kubectl create -f lxd-k8s-model-op1.yaml -kubectl create -f lxd-k8s-model-vol1.yaml -kubectl describe pv -``` - -!!! Important: - The storage classes that will subsequently be created must have names that - are prefixed with the name of the model in use. We've included the model - name of 'lxd-k8s-model' in various places to emphasise the importance of - the model. - -The content of the storage definition files are given below. Typically multiple -charm storage volumes would be required. - -^# lxd-k8s-model-op1.yaml - - kind: PersistentVolume - apiVersion: v1 - metadata: - name: op1 - spec: - capacity: - storage: 1032Mi - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Retain - storageClassName: lxd-k8s-model-operator-storage - hostPath: - path: "/mnt/data/op1" - -^# lxd-k8s-model-vol1.yaml - - kind: PersistentVolume - apiVersion: v1 - metadata: - name: vol1 - spec: - capacity: - storage: 100Mi - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Retain - storageClassName: lxd-k8s-model-charm-storage - hostPath: - path: "/mnt/data/vol1" - -Note that operator storage needs a minimum of 1024 MiB. - -### External storage - -Although the recommended approach is to use Juju-managed storage, Juju does -support externally created storage for both operator storage and charm storage. - -For operator storage, Juju will use this order of precedence for determining -the storage it will use: - - 1. a storage class called `juju-operator-storage` - 1. a storage class with label `juju-storage`, and one of these labels: - 1. `-operator-storage` - 1. `` - 1. `default` - 1. a storage class with label `storageclass.kubernetes.io/is-default-class` - -For charm storage the rules are similar: - - 1. a storage class called `juju-unit-storage` - 1. a storage class with label `juju-storage`, and one of these labels: - 1. `-unit-storage` - 1. `` - 1. `default` - 1. a storage class with label `storageclass.kubernetes.io/is-default-class` - -This documentation will focus on Juju-managed storage only. - -### Operator storage - -Operator storage is set up by defining a Juju storage pool that maps to a -Kubernetes storage class. Here are examples of definitions that use various -Kubernetes storage provisioners: - -For AWS using EBS volumes: - -```bash -juju create-storage-pool operator-storage kubernetes \ - storage-class=juju-operator-storage \ - storage-provisioner=kubernetes.io/aws-ebs \ - parameters.type=gp2 -``` - -For GKE using Persistent Disk: - -```bash -juju create-storage-pool operator-storage kubernetes \ - storage-class=juju-operator-storage \ - storage-provisioner=kubernetes.io/gce-pd \ - parameters.type=pd-standard -``` - -For `microk8s` using built-in hostPath storage: - -```bash -juju create-storage-pool operator-storage kubernetes \ - storage-class=microk8s-hostpath -``` - -```bash -juju create-storage-pool operator-storage kubernetes \ - storage-class=lxd-op-storage \ - storage-provisioner=kubernetes.io/no-provisioner -``` - -```bash -juju create-storage-pool lxd-k8s-pool kubernetes \ - storage-class=lxd-model-charm-storage \ - storage-provisioner=kubernetes.io/no-provisioner -``` - - -### Charm storage - -Kubernetes charms requiring persistent storage can make use of Kubernetes -persistent volumes. Currently, only filesystem storage is supported. - -As with standard charms, storage requirements are stated in the Kubernetes -charm's `metadata.yaml` file: - -```no-highlight -storage: - database: - type: filesystem - location: /var/lib/mysql -``` - -An example is the [mariadb-k8s][staging-mariadb-k8s] charm. +### Define storage classes (if necessary) +### Create storage pools +### Deploy k8s-specific charms ## Configuration @@ -385,15 +217,12 @@ Kubernetes `scale` command. [kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ -[credentials]: ./credentials.md [upstream-kubernetes-docs]: https://kubernetes.io/docs -[upstream-kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes -[upstream-microk8s]: https://microk8s.io [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator -[charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ [upstream-gke-kubernetes]: https://cloud.google.com/kubernetes-engine/ [upstream-dok-kubernetes]: https://www.digitalocean.com/products/kubernetes/ +[upstream-microk8s]: https://microk8s.io From a4cfefd4fa55fb9260c0191abc4bfc28c6550a28 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 15 Nov 2018 17:41:18 -0500 Subject: [PATCH 139/311] edits --- src/en/charms-storage.md | 4 +- src/en/clouds-k8s.md | 83 +++++++++++++++++++++++++++++++--------- 2 files changed, 66 insertions(+), 21 deletions(-) diff --git a/src/en/charms-storage.md b/src/en/charms-storage.md index acb973948..41b766e51 100644 --- a/src/en/charms-storage.md +++ b/src/en/charms-storage.md @@ -18,8 +18,8 @@ to the [PostgreSQL charm][charm-store-postgresql] and the The Ceph examples used here are based on the Ceph cluster described in the document [Installing Ceph][charms-storage-ceph]. -Using storage with Kubernetes is covered in -[Persistent storage and Kubernetes][charms-storage-k8]. +Using storage with Kubernetes is covered on the +[Persistent storage and Kubernetes][charms-storage-k8] page. ## Storage management commands diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 1f7971f8c..24dc0ba15 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -1,9 +1,8 @@ Title: Using Kubernetes with Juju TODO: Should eventually link to k8s-charm developer documentation - Update when storage becomes a Juju drivable aspect. Add architectural overview/diagram Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` - Add charms section when they become available in the charm store (change from staging store to production store) + Change from staging store to production store when available Link to Discourse posts for microk8s, aws-integrator? Write a tutorial or two on building a cluster using the methods listed @@ -48,8 +47,8 @@ To summarise, the steps for using Kubernetes with Juju are: 1. Add the cluster to Juju 1. Add a model 1. Define storage classes (if necessary) - 1. Create storage pools - 1. Deploy k8s-specific charms + 1. Create storage pools (charm storage if necessary) + 1. Deploy a Kubernetes-specific charm ### Obtain a Kubernetes cluster @@ -92,11 +91,12 @@ Machine State DNS Inst id Series AZ Message !!! Note: We've used the staging Charm Store in these instructions as the standard - site does not yet contain the Kubernetes charms and bundles. + site does not yet contain Kubernetes charms and bundles. -**Alternative methods for obtaining a Kubernetes cluster** -Beyond your own custom/bespoke Kubernetes cluster, here is a list of -alternative methods to explore for setting one up: +#### Alternative methods for obtaining a Kubernetes cluster + +Here is a list of alternative methods to explore for setting up a Kubernetes +cluster: 1. Use the 'canonical-kubernetes' bundle, which is a more sophisticated version of what we used above. @@ -106,8 +106,7 @@ alternative methods to explore for setting one up: [Canonical Distribution of Kubernetes][cdk-charm] you can choose the identical minimal install deployed above from the installer's interface. 1. Use [`microk8s`][upstream-microk8s]. With microk8s, you get a local, fully - compliant Kubernetes deployment with dynamic persistent volume support, and - a running ingres controller. + compliant Kubernetes deployment with dynamic persistent volume support. 1. Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. @@ -127,9 +126,9 @@ This is found within the main Kubernetes configuration file. #### Adding a juju-deployed cluster quickly -If the `juju deploy` command was used to deploy the cluster the above file can -be copied over from the Kubernetes master node (and saved as `~/.kube/config`) -in this way: +If Juju was used to deploy the cluster, as we've done in this example, the +above file can be copied over from the Kubernetes master node (and saved as +`~/.kube/config`) in this way: ```bash mkdir ~/.kube @@ -171,16 +170,59 @@ juju add-model lxd-k8s-model lxd-k8s-cloud This will cause a Kubernetes namespace in the cluster to be created that will host all of the pods and other resources for that model. -### Define storage classes (if necessary) +### Define storage classes + +Define a storage class for operator storage if your chosen backing cloud's +storage is not supported natively by Kubernetes. You will need to do the same +for charm storage if your charm has storage requirements (we will do so since +our intended charm will need storage). + +Here, since our example is using an unsupported storage solution (LXD) +we'll create storage classes for both types: + +```bash +kubectl create -f lxd-k8s-model-op1.yaml +kubectl create -f lxd-k8s-model-vol1.yaml +``` + +See [Persistent storage and Kubernetes][charms-storage-k8s] for more +information. + ### Create storage pools -### Deploy k8s-specific charms + +Create storage pools for operator storage and, if needed, charm storage. We +will need to do both for our example: + +```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=lxd-k8s-model-operator-storage \ + storage-provisioner=kubernetes.io/no-provisioner +juju create-storage-pool lxd-k8s-pool kubernetes \ + storage-class=lxd-k8s-model-charm-storage \ + storage-provisioner=kubernetes.io/no-provisioner +``` + +Again, refer to [Persistent storage and Kubernetes][charms-storage-k8s] for +more information. + +### Deploy a Kubernetes-specific charm + +Deploy a Kubernetes charm. This example uses a +[MariaDB charm][charm-store-staging-mariadb-k8s] that will make use of the +previously created charm storage called 'lxd-k8s-pool': + +```bash +juju deploy cs:~wallyworld/mariadb-k8s --storage database=10M,lxd-k8s-pool +``` + +The [Using Juju storage][charms-storage-juju-deploy] page covers the above +syntax. ## Configuration -Juju k8s applications support application specific configuration. This allows -k8s configuration to be used to control how Juju deploys the application on -Kubernetes. The following are supported (these names are the Juju configuration -attribute names; the k8s meaning should be obvious): +Kubernetes charms support Kubernetes-specific settings that influence how Juju +deploys the application. The following are supported (these names are the Juju +configuration attribute names; the Kubernetes meaning should be self-evident): | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| @@ -220,6 +262,9 @@ Kubernetes `scale` command. [upstream-kubernetes-docs]: https://kubernetes.io/docs [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator +[charms-storage-k8s]: ./charms-storage-k8s.md +[charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 +[charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ From 15b3f0743c485a1b0e9ed302946f2e38d8314cf2 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 16 Nov 2018 08:40:37 -0500 Subject: [PATCH 140/311] update notes and install --- src/en/reference-install.md | 16 +++++++-------- src/en/reference-release-notes.md | 34 +++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 8 deletions(-) diff --git a/src/en/reference-install.md b/src/en/reference-install.md index 9663c12e8..842e3f26e 100644 --- a/src/en/reference-install.md +++ b/src/en/reference-install.md @@ -7,9 +7,9 @@ distributions, macOS, and Windows. Development releases are also available for testing. Read on for how to install a stable or development version of Juju on your chosen platform. -## Version 2.4.5 +## Version 2.4.6 -The most recent stable version of Juju is 2.4.5. This is the version we +The most recent stable version of Juju is 2.4.6. This is the version we recommend for production use. See the [Release Notes][release-notes-2]. ### Ubuntu @@ -79,7 +79,7 @@ sudo snap install juju --classic For CentOS, you can download Juju from the following archive and install it manually: -[**juju-2.4.5-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) +[**juju-2.4.6-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) ### macOS @@ -100,7 +100,7 @@ brew upgrade juju A Windows installer is available for Juju and can be found here: -[**juju-setup-2.4.5-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) +[**juju-setup-2.4.6-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) ## Development releases @@ -167,9 +167,9 @@ instructions on how to build Juju from source. [snapcraft]: https://snapcraft.io [snapd-install]: https://snapcraft.io/docs/core/install [juju-new-bug]: https://bugs.launchpad.net/juju/+filebug -[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-setup-2.4.5-signed.exe -[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-setup-2.4.5-signed.exe/+md5 -[juju-centos]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-2.4.5-centos7.tar.gz -[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.5/+download/juju-2.4.5-centos7.tar.gz/+md5 +[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-setup-2.4.6-signed.exe +[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-setup-2.4.6-signed.exe/+md5 +[juju-centos]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-2.4.6-centos7.tar.gz +[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-2.4.6-centos7.tar.gz/+md5 [juju-launchpad-binaries]: https://launchpad.net/juju/+series [centos-and-other-linuxes]: #centos-and-other-linuxes diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index e633662e4..730a7c223 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -5,6 +5,40 @@ Title: Juju Release Notes This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available [here][release-notes-1]. +^# Juju 2.4.6 + + This is primarily a bugfix release for the 2.4 series but comes with one new + feature and several improvements. + + - [LP #1801765](https://bugs.launchpad.net/juju/2.4/+bug/1801765) - goal state calculation for subordinates seems wrong + - [LP #1802033](https://bugs.launchpad.net/juju/2.4/+bug/1802033) - juju bundle-export does not include options, endpoint bindings + + For the full list of fixes and additions, see the + [2.4.6 milestone](https://launchpad.net/juju/+milestone/2.4.6). + + ## Get Juju + + The easiest way to install Juju is by using the `snap` package: + + sudo snap install juju --classic + + Those already using the 'stable' snap channel (the default as per the above + command) should be upgraded automatically. Other packages are available for a + variety of platforms (see the [install documentation][reference-install]). + + ## Feedback appreciated + + Let us know how you're using Juju or of any questions you may have. You can + join us on [Discourse][juju-discourse-forum], send us a message on Twitter + (hashtag `#jujucharms`), or talk to us in the `#juju` IRC channel on + freenode. + + ## More information + + To learn more about Juju visit our home page at + [https://jujucharms.com](https://jujucharms.com). + + ^# Juju 2.4.5 This is primarily a bugfix release for the 2.4 series but comes with one new From 5953f7072f964d8b247d1192b323df9861603338 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 16 Nov 2018 15:14:18 -0500 Subject: [PATCH 141/311] improvments --- src/en/charms-storage-k8s.md | 80 ++++++++++++++++++++++-------------- src/en/clouds-k8s.md | 56 +++++++++++++------------ 2 files changed, 78 insertions(+), 58 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 1a62d2378..5ce8c723e 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -24,15 +24,13 @@ storage: location: /var/lib/mysql ``` - +Currently, only filesystem storage is supported. -Both operator storage and charm storage can be either Juju-managed or managed -externally to Juju (i.e. within Kubernetes itself). Furthermore, Juju-managed -storage can be provisioned either dynamically or statically. +Both operator storage and charm storage can be Juju-managed and this is the +recommended method. However, both can also be managed externally to Juju (i.e. +within Kubernetes itself). + +Juju-managed storage can be provisioned either dynamically or statically. !!! Note: The topic of storage is covered in a non-Kubernetes context on the @@ -40,7 +38,7 @@ storage can be provisioned either dynamically or statically. ### Juju-managed storage -There are two types of persistent storage that Juju can manage: +As mentioned, there are two types of persistent storage that Juju can manage: - dynamically provisioned volumes - statically provisioned volumes @@ -52,11 +50,11 @@ be set up prior to the creation of the storage pool. See [Types of persistent volumes][upstream-kubernetes-volumes] for the list of Kubernetes supported backends. -To define static volumes the below procedure is provided that caters -specifically to the ongoing example used on this page. The example -YAML-formatted files `lxd-op1.yaml` and `lxd-vol1.yaml` define operator storage -and charm storage respectively. Notice how these files allude to LXD, which is -a backing cloud that is not natively supported by Kubernetes. +#### Statically provisioned volumes + +You set up static volumes via storage class definitions. The +[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. +Here is a example procedure: ```bash sudo snap install --classic kubectl @@ -66,15 +64,13 @@ kubectl create -f lxd-k8s-model-vol1.yaml kubectl describe pv ``` -!!! Important: - The storage classes that will subsequently be created must have names that - are prefixed with the name of the model in use. We've included the model - name of 'lxd-k8s-model' in various places to emphasise the importance of - the model. - -The content of the storage definition files are given below. Typically multiple -charm storage volumes would be required. Note that operator storage needs a -minimum of 1024 MiB. +The example YAML-formatted files `lxd-op1.yaml` and `lxd-vol1.yaml` define +volumes for operator storage and charm storage respectively that get created by +the `kubectl` command. + +The content of the storage class definition files are given below. Typically +multiple charm storage volumes would be required. Note that operator storage +needs a minimum of 1024 MiB. ^# lxd-k8s-model-op1.yaml @@ -108,9 +104,18 @@ minimum of 1024 MiB. hostPath: path: "/mnt/data/vol1" -We will show how to create Juju storage pools using our newly-defined storage -classes in section [Creating storage pools][#creating-storage-pools]. +The storage classes names must be prefixed with the name of the model in use. +We've included the model name of 'lxd-k8s-model' in various places to emphasise +the importance of the model. + +We'll show how to create Juju storage pools using our newly-created volumes in +section [Creating storage pools][#creating-storage-pools]. +!!! Important: + Once a static volume is used, it is never re-used, even if the unit/pod is + terminated and the volume is released. Just as static volumes are manually + created, they must also be manually removed. + ### External storage Although the recommended approach is to use Juju-managed storage, Juju does @@ -142,10 +147,19 @@ This documentation will focus on Juju-managed storage only. Juju storage pools are created for both operator storage and charm storage using the `create-storage-pool` command. Both are done by mapping to either a Kubernetes storage class (dynamically provisioned volumes) or to a manually -defined one (statically provisioned volumes). Examples are provided below. +defined one (statically provisioned volumes). The command's syntax is: + +`juju create-storage-pool kubernetes \ + storage-class= \ + storage-provisioner= \ + parameters.type=` -These examples create a Juju storage pool called 'operator-storage' with a -provider type of 'kubernetes'. +The 'pool name' is used at charm deployment time. It is also the `deploy` +command that triggers the actual creation of the Kubernetes storage class when +that storage class is referred to for the first time. + +These next few examples show how to create operator storage pool using various +Kubernetes supported storage provisioners. For AWS using EBS volumes: @@ -180,9 +194,9 @@ juju create-storage-pool operator-storage kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -Creating a charm storage pool is done very similarly. The below example creates -a pool called 'lxd-k8s-pool' using a manually defined storage class called -'lxd-k8s-model-charm-storage': +Creating a charm storage pool is done similarly. The below example creates a +pool arbitrarily called 'lxd-k8s-pool' using a manually defined storage class +called 'lxd-k8s-model-charm-storage': ```bash juju create-storage-pool lxd-k8s-pool kubernetes \ @@ -190,10 +204,14 @@ juju create-storage-pool lxd-k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` +The standard `storage-pools` command is used to list all current Juju storage +pools. + [charms-storage]: ./charms-storage.md [upstream-kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes +[upstream-kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ [#creating-storage-pools]: #creating-storage-pools [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 24dc0ba15..30dbacb81 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -1,7 +1,7 @@ Title: Using Kubernetes with Juju TODO: Should eventually link to k8s-charm developer documentation Add architectural overview/diagram - Consider manually adding a cluster (third-party installs) via `add-cloud` and `add-credential` + Consider manually adding a cluster via `add-cloud` and `add-credential` Change from staging store to production store when available Link to Discourse posts for microk8s, aws-integrator? Write a tutorial or two on building a cluster using the methods listed @@ -15,8 +15,9 @@ most commonly employs Docker as its container technology. ## Juju k8s-specific workflow -The only k8s-specific Juju commands are `add-k8s` and `remove-k8s`. All other -concepts and commands are applied in the traditional Juju manner. +The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and +`scale-application`. All other concepts and commands are applied in the +traditional Juju manner. If the Kubernetes cluster is built with Juju itself (via a bundle) and `juju add-k8s` is run immediately afterwards, the contents of file @@ -218,41 +219,42 @@ juju deploy cs:~wallyworld/mariadb-k8s --storage database=10M,lxd-k8s-pool The [Using Juju storage][charms-storage-juju-deploy] page covers the above syntax. -## Configuration +#### Configuration -Kubernetes charms support Kubernetes-specific settings that influence how Juju -deploys the application. The following are supported (these names are the Juju -configuration attribute names; the Kubernetes meaning should be self-evident): +The below table lists configuration keys supported by Kubernetes charms that +are set at deploy time. Although the key names are for Juju, the corresponding +Kubernetes meaning should be self-evident. | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| -kubernetes-service-type | string | ClusterIP | | -kubernetes-service-external-ips | string | [] | | -kubernetes-service-target-port | string | | | -kubernetes-service-loadbalancer-ip | string | "" | | -kubernetes-service-loadbalancer-sourceranges | string | [] | | -kubernetes-service-externalname | string | "" | | -kubernetes-ingress-class | string | nginx | | -kubernetes-ingress-ssl-redirect | boolean | false | | -kubernetes-ingress-ssl-passthrough | boolean | false | | -kubernetes-ingress-allow-http | boolean | false | | - -There are three other configuration attributes which are not k8s-specific: +`kubernetes-service-type` | string | ClusterIP | | +`kubernetes-service-external-ips` | string | [] | | +`kubernetes-service-target-port` | string | | | +`kubernetes-service-loadbalancer-ip` | string | "" | | +`kubernetes-service-loadbalancer-sourceranges` | string | [] | | +`kubernetes-service-externalname` | string | "" | | +`kubernetes-ingress-class` | string | nginx | | +`kubernetes-ingress-ssl-redirect` | boolean | false | | +`kubernetes-ingress-ssl-passthrough` | boolean | false | | +`kubernetes-ingress-allow-http` | boolean | false | | + +For example: + +```bash +juju deploy mariadb-k8s --config kubernetes-service-loadbalancer-ip=10.1.1.1 +``` + +There are two other keys that are not Kubernetes-specific: | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| -juju-external-hostname | string | | | Mandatory; user specified -juju-application-path | string | "/" | | +`juju-external-hostname` | string | "" | | Mandatory; user specified +`juju-application-path` | string | "/" | | -Attributes 'juju-external-hostname' and 'juju-application-path' control how the +Keys 'juju-external-hostname' and 'juju-application-path' control how the application is exposed externally using a Kubernetes Ingress Resource in conjunction with the configured ingress controller (default: nginx). -Juju uses a deployment controller for each application to manage pod lifecycle, -which allows for the addition or removal of units as normal. It remains -possible to perform these same actions directly in the cluster by way of the -Kubernetes `scale` command. - From fa9e58800e90bd7ad7b029d8132b4ac40631ee50 Mon Sep 17 00:00:00 2001 From: Rick Harding Date: Tue, 20 Nov 2018 07:34:24 -0500 Subject: [PATCH 142/311] Fix = to : in troubleshooting logs yaml sample Per #3193 updated where = should be : for the YAML sample. --- src/en/troubleshooting-logs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/en/troubleshooting-logs.md b/src/en/troubleshooting-logs.md index ce6b989be..a2fa24780 100644 --- a/src/en/troubleshooting-logs.md +++ b/src/en/troubleshooting-logs.md @@ -236,7 +236,7 @@ juju ssh mysql/0 ``` File `/var/lib/juju/agents/unit-mysql-0/agent.conf` is then edited by adding -the line `LOGGING_OVERRIDE=juju=trace` to the 'values' section. +the line `LOGGING_OVERRIDE: juju=trace` to the 'values' section. To be clear, the bottom of the file now looks like: @@ -245,7 +245,7 @@ loggingconfig: =WARNING;unit=DEBUG values: CONTAINER_TYPE: "" NAMESPACE: "" - LOGGING_OVERRIDE=juju=trace + LOGGING_OVERRIDE: juju=trace mongoversion: "0.0" ``` From 72506e61588fe99daa67c0c77ea5724ee535db33 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 20 Nov 2018 08:55:45 -0500 Subject: [PATCH 143/311] new microk8s tutorial page --- src/en/charms-storage-k8s.md | 23 +++++++++-------- src/en/clouds-k8s.md | 50 +++++++++++++++++++----------------- src/en/tutorial-microk8s.md | 24 +++++++++++++++++ 3 files changed, 63 insertions(+), 34 deletions(-) create mode 100644 src/en/tutorial-microk8s.md diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 5ce8c723e..647e1d859 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -104,9 +104,8 @@ needs a minimum of 1024 MiB. hostPath: path: "/mnt/data/vol1" -The storage classes names must be prefixed with the name of the model in use. -We've included the model name of 'lxd-k8s-model' in various places to emphasise -the importance of the model. +One naming convention that works is to have the storage classes names prefixed +with the name of the model in use. We'll show how to create Juju storage pools using our newly-created volumes in section [Creating storage pools][#creating-storage-pools]. @@ -124,20 +123,22 @@ support externally created storage for both operator storage and charm storage. For operator storage, Juju will use this order of precedence for determining the storage it will use: + 1. a storage class called `-juju-operator-storage` 1. a storage class called `juju-operator-storage` - 1. a storage class with label `juju-storage`, and one of these labels: - 1. `-operator-storage` - 1. `` - 1. `default` + 1. a storage class with label key `juju-storage`, with a value set to one of: + - `-operator-storage` + - `` + - `default` 1. a storage class with label `storageclass.kubernetes.io/is-default-class` For charm storage the rules are similar: + 1. a storage class called `-juju-unit-storage` 1. a storage class called `juju-unit-storage` - 1. a storage class with label `juju-storage`, and one of these labels: - 1. `-unit-storage` - 1. `` - 1. `default` + 1. a storage class with label key `juju-storage`, with a value set to one of: + - `-unit-storage` + - `` + - `default` 1. a storage class with label `storageclass.kubernetes.io/is-default-class` This documentation will focus on Juju-managed storage only. diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 30dbacb81..a0a49f2fc 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -13,6 +13,9 @@ applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. +This page assumes you have a good understanding of +[Persistent storage and Kubernetes][charms-storage-k8s]. + ## Juju k8s-specific workflow The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and @@ -42,14 +45,15 @@ First off, a Kubernetes cluster will be required. Essentially, you will use it as you would any other cloud that Juju interacts with: the cluster becomes the backing cloud. -To summarise, the steps for using Kubernetes with Juju are: +The following steps describe the general approach for using Kubernetes with +Juju: 1. Obtain a Kubernetes cluster 1. Add the cluster to Juju 1. Add a model - 1. Define storage classes (if necessary) + 1. Create persistent storage (if necessary) 1. Create storage pools (charm storage if necessary) - 1. Deploy a Kubernetes-specific charm + 1. Deploy a Kubernetes charm ### Obtain a Kubernetes cluster @@ -107,7 +111,8 @@ cluster: [Canonical Distribution of Kubernetes][cdk-charm] you can choose the identical minimal install deployed above from the installer's interface. 1. Use [`microk8s`][upstream-microk8s]. With microk8s, you get a local, fully - compliant Kubernetes deployment with dynamic persistent volume support. + compliant Kubernetes deployment with dynamic persistent volume support. See + tutorial [Using Juju with microk8s][tutorial-microk8s]. 1. Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. @@ -171,12 +176,12 @@ juju add-model lxd-k8s-model lxd-k8s-cloud This will cause a Kubernetes namespace in the cluster to be created that will host all of the pods and other resources for that model. -### Define storage classes +### Create persistent storage -Define a storage class for operator storage if your chosen backing cloud's -storage is not supported natively by Kubernetes. You will need to do the same -for charm storage if your charm has storage requirements (we will do so since -our intended charm will need storage). +Create persistent static volumes for operator storage if your chosen backing +cloud's storage is not supported natively by Kubernetes. You will need to do +the same for charm storage if your charm has storage requirements (we will do +so since our intended charm will need storage). Here, since our example is using an unsupported storage solution (LXD) we'll create storage classes for both types: @@ -186,9 +191,6 @@ kubectl create -f lxd-k8s-model-op1.yaml kubectl create -f lxd-k8s-model-vol1.yaml ``` -See [Persistent storage and Kubernetes][charms-storage-k8s] for more -information. - ### Create storage pools Create storage pools for operator storage and, if needed, charm storage. We @@ -203,17 +205,14 @@ juju create-storage-pool lxd-k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -Again, refer to [Persistent storage and Kubernetes][charms-storage-k8s] for -more information. - -### Deploy a Kubernetes-specific charm +### Deploy a Kubernetes charm -Deploy a Kubernetes charm. This example uses a -[MariaDB charm][charm-store-staging-mariadb-k8s] that will make use of the -previously created charm storage called 'lxd-k8s-pool': +It's time to deploy a Kubernetes-specific charm. Our example uses a +[MariaDB charm][charm-store-staging-mariadb-k8s] that will use the previously +created charm storage called 'lxd-k8s-pool': ```bash -juju deploy cs:~wallyworld/mariadb-k8s --storage database=10M,lxd-k8s-pool +juju deploy cs:~wallyworld/mariadb-k8s --storage database=lxd-k8s-pool,10M ``` The [Using Juju storage][charms-storage-juju-deploy] page covers the above @@ -222,8 +221,10 @@ syntax. #### Configuration The below table lists configuration keys supported by Kubernetes charms that -are set at deploy time. Although the key names are for Juju, the corresponding -Kubernetes meaning should be self-evident. +are set at deploy time. The corresponding Kubernetes meaning can be obtained +from the Kubernetes documentation for +[Services][upstream-kubernetes-docs-service] and +[Ingress][upstream-kubernetes-docs-ingress]. | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| @@ -248,7 +249,7 @@ There are two other keys that are not Kubernetes-specific: | Key | Type | Default | Valid values | Comments | |:----------------------------------------------|---------|------------------|--------------|:-----------------------------| -`juju-external-hostname` | string | "" | | Mandatory; user specified +`juju-external-hostname` | string | "" | | `juju-application-path` | string | "/" | | Keys 'juju-external-hostname' and 'juju-application-path' control how the @@ -262,11 +263,14 @@ conjunction with the configured ingress controller (default: nginx). [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [upstream-kubernetes-docs]: https://kubernetes.io/docs +[upstream-kubernetes-docs-service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[upstream-kubernetes-docs-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator [charms-storage-k8s]: ./charms-storage-k8s.md [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy +[tutorial-microk8s]: ./tutorial-microk8s.md [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md new file mode 100644 index 000000000..c1803bfe4 --- /dev/null +++ b/src/en/tutorial-microk8s.md @@ -0,0 +1,24 @@ +Title: Using Juju with microk8s + +# Using Juju with microk8s + +*This is in connection with the [Using Kubernetes with Juju][clouds-k8s] page. +See that resource for background information.* + +This tutorial has the following pre-requisites: + + 1. Juju is installed (see ????) + 1. +udo apt update && sudo apt -y full-upgrade && sudo snap install lxd && sudo apt purge -y liblxc1 lxcfs lxd lxd-client && sudo snap install --edge --classic juju && sudo reboot +sudo snap install --edge --classic microk8s +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd-microk8s +microk8s.enable dns storage +microk8s.config | juju add-k8s lxd-microk8s-cloud +juju add-model lxd-microk8s-model lxd-microk8s-cloud +juju create-storage-pool operator-storage kubernetes storage-class=microk8s-hostpath +juju create-storage-pool mariadb-pv kubernetes storage-class=microk8s-hostpath +juju deploy cs:~wallyworld/mariadb-k8s --storage database=mariadb-pv,10M + + + +[clouds-k8s]: ./clouds-k8s.md From 0613fd2eb35fb07b18767611b9af44516a40e6a8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 20 Nov 2018 14:30:09 -0500 Subject: [PATCH 144/311] fill in microk8s tutorial --- src/en/tutorial-microk8s.md | 105 +++++++++++++++++++++++++++++++++--- 1 file changed, 98 insertions(+), 7 deletions(-) diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index c1803bfe4..7936695a2 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -7,18 +7,109 @@ See that resource for background information.* This tutorial has the following pre-requisites: - 1. Juju is installed (see ????) - 1. -udo apt update && sudo apt -y full-upgrade && sudo snap install lxd && sudo apt purge -y liblxc1 lxcfs lxd lxd-client && sudo snap install --edge --classic juju && sudo reboot -sudo snap install --edge --classic microk8s -juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd-microk8s + +# Software installation + +These instructions assume you're using a fresh Ubuntu 18.04 LTS install, or at +least one that is not already using either Juju or LXD. This tutorial installs +Juju, LXD, and microk8s as snaps. It also removes a possibly existing LXD deb +package. Do not invoke the purge command below if you're currently using LXD! + +```bash +sudo snap install juju --classic +sudo snap install lxd +sudo snap install microk8s --classic +sudo apt purge -y liblxc1 lxcfs lxd lxd-client +``` + +Enable some microk8s addons that will provide DNS and storage class support: + +```bash microk8s.enable dns storage -microk8s.config | juju add-k8s lxd-microk8s-cloud -juju add-model lxd-microk8s-model lxd-microk8s-cloud +``` + +This will bring about changes to the cluster. See what's going on with the +`microk8s.kubectl` command: + +```bash +microk8s.kubectl get all --all-namespaces +``` + +It's time to bring Juju in to the picture by creating a controller. At the time +of writing the production Charm Store was not yet updated with Kubernetes +charms. For now, we'll use the staging site instead: + +```bash +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd +``` + +This will take about five minutes to finish. + +The `add-k8s` command adds the new Kubernetes cluster to Juju's list of known +clouds. Here, we arbitrarily call the new cloud 'microk8s-cloud': + +```bash +microk8s.config | juju add-k8s microk8s-cloud +``` + +Confirm this by running `juju clouds`. + +At this point we have something interesting going on. The controller we created +earlier is now atypically associated with two clouds: the 'localhost' cloud and +the 'microk8s-cloud' cloud. So when we want to create a model we'll need +explicitly state which cloud to place the new model in. We'll do this now by +adding new model 'k8s-model' to cloud 'microk8s-cloud': + +```bash +juju add-model k8s-model microk8s-cloud +``` + +The output to `juju models` should now look very similar to: + +```no-highlight +Controller: lxd + +Model Cloud/Region Status Machines Access Last connection +controller localhost/localhost available 1 admin just now +default localhost/localhost available 0 admin 26 minutes ago +k8s-model* microk8s-cloud available 0 admin never connected +``` + +One of the benefits of using `microk8s` is that we get dynamically provisioned +storage out of the box. Below we have Juju create two storage pools, one for +operator storage and one for charm storage: + +```bash juju create-storage-pool operator-storage kubernetes storage-class=microk8s-hostpath juju create-storage-pool mariadb-pv kubernetes storage-class=microk8s-hostpath +``` + +See the [Persistent storage and Kubernetes][charms-storage-k8s] page for +in-depth information on how Kubernetes storage works with Juju. + +We can deploy a Kubernetes charm. For example, here we deploy a charm by +requesting the use of the 'mariadb-pv' charm storage pool we just set up: + +```bash juju deploy cs:~wallyworld/mariadb-k8s --storage database=mariadb-pv,10M +``` + +The output to `juju status` should soon look like: + +```no-highlight +Model Controller Cloud/Region Version SLA Timestamp +k8s-model lxd microk8s-cloud 2.5-beta2 unsupported 18:55:56Z + +App Version Status Scale Charm Store Rev OS Address Notes +mariadb-k8s active 1 mariadb-k8s jujucharms 13 kubernetes 10.152.183.209 + +Unit Workload Agent Address Ports Message +mariadb-k8s/0* active idle 10.1.1.5 3306/TCP +``` + [clouds-k8s]: ./clouds-k8s.md +[upstream-microk8s]: https://microk8s.io +[charms-storage-k8s]: ./charms-storage-k8s.md From 39d42a74cccca5d0fb2462bbeb9b1f7540ecc364 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 20 Nov 2018 16:32:09 -0500 Subject: [PATCH 145/311] add more command output --- src/en/tutorial-microk8s.md | 101 +++++++++++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 7 deletions(-) diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index 7936695a2..482e1c5e7 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -1,14 +1,23 @@ Title: Using Juju with microk8s +TODO: Add a link to the Ubuntu tutorial "Introducing microk8s" (when published) # Using Juju with microk8s -*This is in connection with the [Using Kubernetes with Juju][clouds-k8s] page. -See that resource for background information.* +*This is in connection to the topic of +[Using Kubernetes with Juju][clouds-k8s]. See that resource for background +information.* -This tutorial has the following pre-requisites: +Juju is compatible with the [microk8s][upstream-microk8s] project, which aims +to provide "a full Kubernetes system in under 60 seconds". It is quite +remarkable actually. It is composed of pure upstream binaries, runs all +services natively (i.e. no virtual machines or containers), and is fully +[CNCF certified][upstream-cncf]. This option is perfect for testing Kubernetes +on your laptop. Using it with Juju is icing on the cake! +Since microk8s is running locally we'll be using a local LXD cloud to create a +Juju controller. -# Software installation +## Installing the software These instructions assume you're using a fresh Ubuntu 18.04 LTS install, or at least one that is not already using either Juju or LXD. This tutorial installs @@ -35,7 +44,36 @@ This will bring about changes to the cluster. See what's going on with the microk8s.kubectl get all --all-namespaces ``` -It's time to bring Juju in to the picture by creating a controller. At the time +Sample output: + +```no-highlight +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system pod/hostpath-provisioner-7d7c578f6b-rc6zz 1/1 Running 0 5m47s +kube-system pod/kube-dns-67b548dcff-dlpgn 3/3 Running 0 5m53s + +NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +default service/kubernetes ClusterIP 10.152.183.1 443/TCP 23m +kube-system service/kube-dns ClusterIP 10.152.183.10 53/UDP,53/TCP 5m53s + +NAMESPACE NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +kube-system deployment.apps/hostpath-provisioner 1 1 1 1 5m47s +kube-system deployment.apps/kube-dns 1 1 1 1 5m53s + +NAMESPACE NAME DESIRED CURRENT READY AGE +kube-system replicaset.apps/hostpath-provisioner-7d7c578f6b 1 1 1 5m47s +Kube-system replicaset.apps/kube-dns-67b548dcff 1 1 1 5m53s +``` + +Later we'll see how this output changes once we deploy a charm. + +## Creating a controller + +Juju always needs a controller as a central management machine. Once this +machine is established all Juju-deployed applications will be contained within +the Kubernetes cluster itself; Juju deployments will not cause LXD containers +to be created. + +So let's bring Juju into the picture by creating a controller now. At the time of writing the production Charm Store was not yet updated with Kubernetes charms. For now, we'll use the staging site instead: @@ -43,7 +81,10 @@ charms. For now, we'll use the staging site instead: juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd ``` -This will take about five minutes to finish. +This will take about five minutes to finish. After which we'll have a +controller called 'lxd' that is based on the 'localhost' cloud. + +## Adding the cluster to Juju The `add-k8s` command adds the new Kubernetes cluster to Juju's list of known clouds. Here, we arbitrarily call the new cloud 'microk8s-cloud': @@ -54,6 +95,8 @@ microk8s.config | juju add-k8s microk8s-cloud Confirm this by running `juju clouds`. +## Adding a model + At this point we have something interesting going on. The controller we created earlier is now atypically associated with two clouds: the 'localhost' cloud and the 'microk8s-cloud' cloud. So when we want to create a model we'll need @@ -75,6 +118,8 @@ default localhost/localhost available 0 admin 26 minutes ago k8s-model* microk8s-cloud available 0 admin never connected ``` +## Adding storage + One of the benefits of using `microk8s` is that we get dynamically provisioned storage out of the box. Below we have Juju create two storage pools, one for operator storage and one for charm storage: @@ -87,6 +132,8 @@ juju create-storage-pool mariadb-pv kubernetes storage-class=microk8s-hostpath See the [Persistent storage and Kubernetes][charms-storage-k8s] page for in-depth information on how Kubernetes storage works with Juju. +## Deploying a Kubernetes charm + We can deploy a Kubernetes charm. For example, here we deploy a charm by requesting the use of the 'mariadb-pv' charm storage pool we just set up: @@ -94,7 +141,7 @@ requesting the use of the 'mariadb-pv' charm storage pool we just set up: juju deploy cs:~wallyworld/mariadb-k8s --storage database=mariadb-pv,10M ``` -The output to `juju status` should soon look like: +The output to `juju status` should soon look like the following: ```no-highlight Model Controller Cloud/Region Version SLA Timestamp @@ -107,9 +154,49 @@ Unit Workload Agent Address Ports Message mariadb-k8s/0* active idle 10.1.1.5 3306/TCP ``` +In contrast to standard Juju behaviour, there are no machines listed here. +Let's see what has happened within the cluster: + +```bash +microk8s.kubectl get all --all-namespaces +``` + +New sample output: + +```no-highlight +NAMESPACE NAME READY STATUS RESTARTS AGE +k8s-model pod/juju-mariadb-k8s-0 1/1 Running 0 140m +k8s-model pod/juju-operator-mariadb-k8s-0 1/1 Running 0 140m +kube-system pod/hostpath-provisioner-7d7c578f6b-rc6zz 1/1 Running 0 3h19m +kube-system pod/kube-dns-67b548dcff-dlpgn 3/3 Running 0 3h19m + +NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +default service/kubernetes ClusterIP 10.152.183.1 443/TCP 3h36m +k8s-model service/juju-mariadb-k8s ClusterIP 10.152.183.209 3306/TCP 140m +kube-system service/kube-dns ClusterIP 10.152.183.10 53/UDP,53/TCP 3h19m + +NAMESPACE NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +kube-system deployment.apps/hostpath-provisioner 1 1 1 1 3h19m +kube-system deployment.apps/kube-dns 1 1 1 1 3h19m + +NAMESPACE NAME DESIRED CURRENT READY AGE +kube-system replicaset.apps/hostpath-provisioner-7d7c578f6b 1 1 1 3h19m +kube-system replicaset.apps/kube-dns-67b548dcff 1 1 1 3h19m + +NAMESPACE NAME DESIRED CURRENT AGE +k8s-model statefulset.apps/juju-mariadb-k8s 1 1 140m +K8s-model statefulset.apps/juju-operator-mariadb-k8s 1 1 140m +``` + +You can easily scan the changes on the left hand side by recalling the model +name we chose: 'k8s-model'. + +Felicitations all around! + [clouds-k8s]: ./clouds-k8s.md [upstream-microk8s]: https://microk8s.io +[upstream-cncf]: https://www.cncf.io/certification/software-conformance/ [charms-storage-k8s]: ./charms-storage-k8s.md From 86cffcd0872b34609648f0b9f13039364f8f4a5a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 20 Nov 2018 19:06:10 -0500 Subject: [PATCH 146/311] finish tutorial --- src/en/tutorial-microk8s.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index 482e1c5e7..8942f8f94 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -188,10 +188,21 @@ k8s-model statefulset.apps/juju-mariadb-k8s 1 1 140 K8s-model statefulset.apps/juju-operator-mariadb-k8s 1 1 140m ``` -You can easily scan the changes on the left hand side by recalling the model -name we chose: 'k8s-model'. +You can easily identify the changes, as compared to the initial output, by +scanning the left hand side for the model name we chose: 'k8s-model', which +ends up being the Kubernetes "namespace". -Felicitations all around! +To get information on pod 'juju-mariadb-k8s-0' you need to refer to the +namespace (since it's not the 'default' namespace) in this way: + +```bash +microk8s.kubectl describe pods -n k8s-model juju-mariadb-k8s-0 +``` + +The output is too voluminous to include here. See the upstream documentation on +viewing cluster information [here][upstream-kubectl-viewing]. + +That's the end of this tutorial. Felicitations for making it this far! @@ -200,3 +211,4 @@ Felicitations all around! [upstream-microk8s]: https://microk8s.io [upstream-cncf]: https://www.cncf.io/certification/software-conformance/ [charms-storage-k8s]: ./charms-storage-k8s.md +[upstream-kubectl-viewing]: https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-finding-resources From fe24a4fbb24060bbff4b4c002b31e00f9828985a Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 21 Nov 2018 12:54:29 -0500 Subject: [PATCH 147/311] tutorial QA and ending notes --- src/en/tutorial-microk8s.md | 51 +++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index 8942f8f94..6d8d56edb 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -1,5 +1,5 @@ Title: Using Juju with microk8s -TODO: Add a link to the Ubuntu tutorial "Introducing microk8s" (when published) +TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1804495 # Using Juju with microk8s @@ -14,15 +14,16 @@ services natively (i.e. no virtual machines or containers), and is fully [CNCF certified][upstream-cncf]. This option is perfect for testing Kubernetes on your laptop. Using it with Juju is icing on the cake! -Since microk8s is running locally we'll be using a local LXD cloud to create a -Juju controller. +Since microk8s runs locally we'll be using a local LXD cloud to create a Juju +controller. ## Installing the software -These instructions assume you're using a fresh Ubuntu 18.04 LTS install, or at -least one that is not already using either Juju or LXD. This tutorial installs -Juju, LXD, and microk8s as snaps. It also removes a possibly existing LXD deb -package. Do not invoke the purge command below if you're currently using LXD! +These instructions assume that you're using a fresh Ubuntu 18.04 LTS install, +or at least one that is not already using either Juju or LXD. This tutorial +installs Juju, LXD, and microk8s as snaps. It also removes a possibly existing +LXD deb package. Do not invoke the purge command below if you're currently +using LXD! ```bash sudo snap install juju --classic @@ -64,7 +65,7 @@ kube-system replicaset.apps/hostpath-provisioner-7d7c578f6b 1 1 Kube-system replicaset.apps/kube-dns-67b548dcff 1 1 1 5m53s ``` -Later we'll see how this output changes once we deploy a charm. +Later we'll see how this output will change once a charm is deployed. ## Creating a controller @@ -199,10 +200,37 @@ namespace (since it's not the 'default' namespace) in this way: microk8s.kubectl describe pods -n k8s-model juju-mariadb-k8s-0 ``` -The output is too voluminous to include here. See the upstream documentation on -viewing cluster information [here][upstream-kubectl-viewing]. +The output is too voluminous to include here. See the +[upstream documentation][upstream-kubectl-viewing] on different ways of viewing +cluster information. -That's the end of this tutorial. Felicitations for making it this far! +## Removing configuration and software + +To remove all traces of microk8s and its configuration follow these steps: + +```bash +juju destroy-model -y --destroy-storage k8s-model +juju remove-cloud microk8s-cloud +microk8s.reset +sudo snap remove microk8s +``` + +This leaves us with LXD and Juju installed as well as a LXD controller. To +remove even those things proceed as follows: + +```bash +juju destroy-controller -y lxd +sudo snap remove lxd +sudo snap remove juju +``` + +That's the end of this tutorial! + +## Next steps + +For more experience with a standalone (non-Juju) microk8s installation you can +go through Ubuntu tutorial +[Install a local Kubernetes with microk8s][ubuntu-tutorial_kubernetes-microk8s]. @@ -212,3 +240,4 @@ That's the end of this tutorial. Felicitations for making it this far! [upstream-cncf]: https://www.cncf.io/certification/software-conformance/ [charms-storage-k8s]: ./charms-storage-k8s.md [upstream-kubectl-viewing]: https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-finding-resources +[ubuntu-tutorial_kubernetes-microk8s]: https://tutorials.ubuntu.com/tutorial/install-a-local-kubernetes-with-microk8s From 37b8eb2d9fbc2b0333ff20fe436f918a54bd52ad Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 21 Nov 2018 18:58:10 -0500 Subject: [PATCH 148/311] improvements to storage explanation and main example --- src/en/charms-storage-k8s.md | 163 ++++++++++++++++++++--------------- src/en/clouds-k8s.md | 62 ++++++------- 2 files changed, 118 insertions(+), 107 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 647e1d859..86dc1136c 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -1,6 +1,7 @@ Title: Persistent storage and Kubernetes TODO: Add how to create external storage Write a tutorial or two on using storage + How to remove a static volume? # Persistent storage and Kubernetes @@ -13,9 +14,9 @@ required. We call this type of storage *operator storage*. In addition, a Kubernetes charm may itself require persistent storage (e.g. the [mariadb-k8s][charm-store-staging-mariadb-k8s] charm). Its Juju storage -pool also has a provider type of 'kubernetes'. We call this type of -storage *charm storage*. As with standard charms, storage requirements are -stated in the charm's `metadata.yaml` file: +pool also has a provider type of 'kubernetes'. We call this type of storage +*charm storage* (or unit storage). As with standard charms, storage +requirements are stated in the charm's `metadata.yaml` file: ```no-highlight storage: @@ -53,26 +54,24 @@ Kubernetes supported backends. #### Statically provisioned volumes You set up static volumes via storage class definitions. The -[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. -Here is a example procedure: +[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. Here is a example procedure: ```bash sudo snap install --classic kubectl -sudo mkdir -p /mnt/data/{op1,vol1} -kubectl create -f lxd-k8s-model-op1.yaml -kubectl create -f lxd-k8s-model-vol1.yaml +kubectl create -f charm-storage-vol1.yaml +kubectl create -f operator-storage.yaml kubectl describe pv ``` -The example YAML-formatted files `lxd-op1.yaml` and `lxd-vol1.yaml` define -volumes for operator storage and charm storage respectively that get created by -the `kubectl` command. +The example YAML-formatted files `operator-storage.yaml` and +`charm-storage-vol1.yaml` define volumes for operator storage and charm storage +respectively that get created by the `kubectl` command. The content of the storage class definition files are given below. Typically multiple charm storage volumes would be required. Note that operator storage needs a minimum of 1024 MiB. -^# lxd-k8s-model-op1.yaml +^# charm-storage-vol1.yaml kind: PersistentVolume apiVersion: v1 @@ -84,11 +83,11 @@ needs a minimum of 1024 MiB. accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: lxd-k8s-model-operator-storage + storageClassName: k8s-model-juju-operator-storage hostPath: - path: "/mnt/data/op1" + path: "/mnt/data/vol1" -^# lxd-k8s-model-vol1.yaml +^# operator-storage.yaml kind: PersistentVolume apiVersion: v1 @@ -100,48 +99,22 @@ needs a minimum of 1024 MiB. accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: lxd-k8s-model-charm-storage + storageClassName: k8s-model-juju-unit-storage hostPath: - path: "/mnt/data/vol1" + path: "/mnt/data/op1" -One naming convention that works is to have the storage classes names prefixed -with the name of the model in use. +!!! Important: + The storage class name for a statically provisioned volume must be prefixed + with the name of the intended model. In the examples above, the model name + is 'k8s-model'. The remainder of the name, for both operator and charm + storage, are fixed. This is explained again further on. We'll show how to create Juju storage pools using our newly-created volumes in -section [Creating storage pools][#creating-storage-pools]. +the next section. -!!! Important: - Once a static volume is used, it is never re-used, even if the unit/pod is - terminated and the volume is released. Just as static volumes are manually - created, they must also be manually removed. - -### External storage - -Although the recommended approach is to use Juju-managed storage, Juju does -support externally created storage for both operator storage and charm storage. - -For operator storage, Juju will use this order of precedence for determining -the storage it will use: - - 1. a storage class called `-juju-operator-storage` - 1. a storage class called `juju-operator-storage` - 1. a storage class with label key `juju-storage`, with a value set to one of: - - `-operator-storage` - - `` - - `default` - 1. a storage class with label `storageclass.kubernetes.io/is-default-class` - -For charm storage the rules are similar: - - 1. a storage class called `-juju-unit-storage` - 1. a storage class called `juju-unit-storage` - 1. a storage class with label key `juju-storage`, with a value set to one of: - - `-unit-storage` - - `` - - `default` - 1. a storage class with label `storageclass.kubernetes.io/is-default-class` - -This documentation will focus on Juju-managed storage only. +Once a static volume is used, it is never re-used, even if the unit/pod is +terminated and the volume is released. Just as static volumes are manually +created, they must also be manually removed. ### Creating storage pools @@ -155,14 +128,26 @@ defined one (statically provisioned volumes). The command's syntax is: storage-provisioner= \ parameters.type=` -The 'pool name' is used at charm deployment time. It is also the `deploy` -command that triggers the actual creation of the Kubernetes storage class when -that storage class is referred to for the first time. +For charm storage, the 'pool name' is referenced at charm deployment time by +the `deploy` command. It is also this command that triggers the actual creation +of the Kubernetes storage class when that storage class is referred to for the +first time. + +The pool name for operator storage *must* be called 'operator-storage' while a +pool name for charm storage is arbitrary. -These next few examples show how to create operator storage pool using various -Kubernetes supported storage provisioners. +The storage class name for operator storage *must* be called +'juju-operator-storage' while a storage class name for charm storage *must* be +called 'juju-unit-storage'. -For AWS using EBS volumes: +The standard `storage-pools` command is used to list Juju storage pools. + +#### Creating operator storage pools + +The below examples show how to create operator storage pools for various +scenarios. + +For AWS using EBS volumes (dynamically provisioned): ```bash juju create-storage-pool operator-storage kubernetes \ @@ -171,7 +156,7 @@ juju create-storage-pool operator-storage kubernetes \ parameters.type=gp2 ``` -For GKE using Persistent Disk: +For GKE using Persistent Disk (dynamically provisioned): ```bash juju create-storage-pool operator-storage kubernetes \ @@ -180,33 +165,73 @@ juju create-storage-pool operator-storage kubernetes \ parameters.type=pd-standard ``` -For `microk8s` using built-in hostPath storage: +For `microk8s` using built-in hostPath storage (dynamically provisioned): ```bash juju create-storage-pool operator-storage kubernetes \ storage-class=microk8s-hostpath ``` -For a manually defined storage class called 'lxd-k8s-model-operator-storage': +For LXD (statically provisioned): ```bash juju create-storage-pool operator-storage kubernetes \ - storage-class=lxd-k8s-model-operator-storage \ + storage-class=juju-operator-storage \ storage-provisioner=kubernetes.io/no-provisioner ``` -Creating a charm storage pool is done similarly. The below example creates a -pool arbitrarily called 'lxd-k8s-pool' using a manually defined storage class -called 'lxd-k8s-model-charm-storage': +!!! Important: + When creating a pool with the 'no-provisioner' type, Juju will prefix the + current model's name to the stated storage class name. In the above + example, assuming a model name of 'k8s-model', the final storage class name + associated with the pool becomes 'k8s-model-juju-operator-storage'. It is + this name that you must use when defining a static volume (YAML file). + +#### Creating charm storage pools + +Creating a charm storage pool is done very similarly to creating an operator +storage pool. The below example creates a pool arbitrarily called 'k8s-pool' +that uses static volumes: ```bash -juju create-storage-pool lxd-k8s-pool kubernetes \ - storage-class=lxd-k8s-model-charm-storage \ +juju create-storage-pool k8s-pool kubernetes \ + storage-class=juju-unit-storage \ storage-provisioner=kubernetes.io/no-provisioner ``` -The standard `storage-pools` command is used to list all current Juju storage -pools. +As with the operator storage static volume scenario, the final storage class +name associated with pool 'k8s-pool', assuming a model of 'k8s-model', becomes +'k8s-model-juju-unit-storage'. + +### External storage and storage precedence rules + +Although the recommended approach is to use Juju-managed storage, Juju does +support externally created storage for both operator storage and charm storage. + +For operator storage, Juju will use this order of precedence for determining +the storage it will use: + + 1. a storage class called `-juju-operator-storage` + 1. a storage class called `juju-operator-storage` + 1. a storage class with label key `juju-storage`, with a value set to one of: + - `-operator-storage` + - `` + - `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +For charm storage the rules are similar: + + 1. a storage class called `-juju-unit-storage` + 1. a storage class called `juju-unit-storage` + 1. a storage class with label key `juju-storage`, with a value set to one of: + - `-unit-storage` + - `` + - `default` + 1. a storage class with label `storageclass.kubernetes.io/is-default-class` + +Notice that for both operator and charm storage, the first two rules account +for Juju-managed statically provisioned volumes and dynamically provisioned +volumes, respectively. diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index a0a49f2fc..95670fc1e 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -3,8 +3,8 @@ TODO: Should eventually link to k8s-charm developer documentation Add architectural overview/diagram Consider manually adding a cluster via `add-cloud` and `add-credential` Change from staging store to production store when available - Link to Discourse posts for microk8s, aws-integrator? - Write a tutorial or two on building a cluster using the methods listed + Link to Discourse posts on aws-integrator? + Write another tutorial on building a cluster using the methods listed # Using Kubernetes with Juju @@ -71,32 +71,32 @@ Sample output to `juju status` looks like this: ```no-highlight Model Controller Cloud/Region Version SLA Timestamp -default lxd-k8s localhost/localhost 2.5-beta1 unsupported 17:38:29Z +default lxd-k8s localhost/localhost 2.5-beta2 unsupported 22:22:14Z App Version Status Scale Charm Store Rev OS Notes easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu kubernetes-master 1.12.2 waiting 1 kubernetes-master jujucharms 219 ubuntu exposed -kubernetes-worker 1.12.2 active 1 kubernetes-worker jujucharms 239 ubuntu exposed +kubernetes-worker 1.12.2 waiting 1 kubernetes-worker jujucharms 239 ubuntu exposed Unit Workload Agent Machine Public address Ports Message -easyrsa/0* active idle 0/lxd/0 10.232.236.186 Certificate Authority connected. -etcd/0* active idle 0 10.80.187.237 2379/tcp Healthy with 1 known peer -kubernetes-master/0* waiting idle 0 10.80.187.237 6443/tcp Waiting for kube-system pods to start - flannel/0* active idle 10.80.187.237 Flannel subnet 10.1.24.1/24 -kubernetes-worker/0* active idle 1 10.80.187.177 80/tcp,443/tcp Kubernetes worker running. - flannel/1 active idle 10.80.187.177 Flannel subnet 10.1.34.1/24 +easyrsa/0* active idle 0/lxd/0 10.10.19.148 Certificate Authority connected. +etcd/0* active idle 0 10.234.141.194 2379/tcp Healthy with 1 known peer +kubernetes-master/0* waiting idle 0 10.234.141.194 6443/tcp Waiting for kube-system pods to start + flannel/0* active idle 10.234.141.194 Flannel subnet 10.1.45.1/24 +kubernetes-worker/0* waiting idle 1 10.234.141.32 80/tcp,443/tcp Waiting for kubelet to start. + flannel/1 active idle 10.234.141.32 Flannel subnet 10.1.37.1/24 Machine State DNS Inst id Series AZ Message -0 started 10.80.187.237 juju-2ad61f-0 bionic Running -0/lxd/0 started 10.232.236.186 juju-2ad61f-0-lxd-0 bionic Container started -1 started 10.80.187.177 juju-2ad61f-1 bionic Running +0 started 10.234.141.194 juju-7c937e-0 bionic Running +0/lxd/0 started 10.10.19.148 juju-7c937e-0-lxd-0 bionic Container started +1 started 10.234.141.32 juju-7c937e-1 bionic Running ``` !!! Note: We've used the staging Charm Store in these instructions as the standard - site does not yet contain Kubernetes charms and bundles. + site does not yet support Kubernetes charms and bundles. #### Alternative methods for obtaining a Kubernetes cluster @@ -146,31 +146,17 @@ copied configuration file from the specified path. This allows us to quickly add the cluster-cloud, which we have arbitrarily called 'lxd-k8s-cloud': ```bash -juju add-k8s lxd-k8s-cloud +juju add-k8s k8s-cloud ``` -Now confirm the successful addition of the cloud: - -```bash -juju clouds -``` - -Here is a partial output: - -```no-highlight -Cloud Regions Default Type Description -. -. -. -lxd-k8s-cloud 0 kubernetes -``` +Now confirm the successful addition of the cloud with the `clouds` command. ### Add a model Add a model in the usual way: ```bash -juju add-model lxd-k8s-model lxd-k8s-cloud +juju add-model k8s-model k8s-cloud ``` This will cause a Kubernetes namespace in the cluster to be created that will @@ -183,12 +169,12 @@ cloud's storage is not supported natively by Kubernetes. You will need to do the same for charm storage if your charm has storage requirements (we will do so since our intended charm will need storage). -Here, since our example is using an unsupported storage solution (LXD) -we'll create storage classes for both types: +Here, since our example is using an unsupported storage solution (LXD) we'll +create static volumes for both types: ```bash -kubectl create -f lxd-k8s-model-op1.yaml -kubectl create -f lxd-k8s-model-vol1.yaml +kubectl create -f charm-storage-vol1.yaml +kubectl create -f operator-storage.yaml ``` ### Create storage pools @@ -198,10 +184,10 @@ will need to do both for our example: ```bash juju create-storage-pool operator-storage kubernetes \ - storage-class=lxd-k8s-model-operator-storage \ + storage-class=juju-operator-storage \ storage-provisioner=kubernetes.io/no-provisioner -juju create-storage-pool lxd-k8s-pool kubernetes \ - storage-class=lxd-k8s-model-charm-storage \ +juju create-storage-pool k8s-pool kubernetes \ + storage-class=juju-unit-storage \ storage-provisioner=kubernetes.io/no-provisioner ``` From 1ef5ceef27cd34ba520750c271e5b37eb1c3b550 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 22 Nov 2018 13:00:23 -0500 Subject: [PATCH 149/311] add bundles support --- src/en/charms-bundles.md | 33 +++++++++++++++++++++++ src/en/charms-deploying.md | 8 ++++++ src/en/charms-storage-k8s.md | 51 +++++++++++++++++++++++++----------- src/en/clouds-k8s.md | 38 +++++++++++++++++++++++---- 4 files changed, 109 insertions(+), 21 deletions(-) diff --git a/src/en/charms-bundles.md b/src/en/charms-bundles.md index e70356cc2..cfda50acf 100644 --- a/src/en/charms-bundles.md +++ b/src/en/charms-bundles.md @@ -52,6 +52,39 @@ machines: constraints: "arch=amd64 cores=1 cpu-power=100 mem=1740 root-disk=8192" ``` +### Kubernetes bundles + +A Kubernetes bundle differs from a standard bundle in the following ways: + + - key 'bundle' is given the value of 'kubernetes' + - key 'num_units' is replaced by key 'scale' + - key 'to' is replaced by key 'placement' + +The value of 'placement' is a key=value pair and is used as a Kubernetes node +selector. + +For example: + +```no-highlight +bundle: kubernetes +applications: + mariadb: + charm: cs:~wallyworld/mariadb-k8s + scale: 2 + constraints: mem=1G + options: + dataset-size: 70% + storage: + database: 20M,mariadb-pv + gitlab: + charm: cs:~wallyworld/gitlab-k8s + placement: foo=bar + scale: 1 +relations: + - - gitlab:mysql + - mariadb:server +``` + ## Deploying bundles A bundle is deployed just like a regular charm is: diff --git a/src/en/charms-deploying.md b/src/en/charms-deploying.md index 5470d7f1d..25441754e 100644 --- a/src/en/charms-deploying.md +++ b/src/en/charms-deploying.md @@ -1,6 +1,7 @@ Title: Deploying applications TODO: Add 'centos' and 'windows' stuff to series talk Hardcoded: Ubuntu codenames + Should link to bundles page table_of_contents: True # Deploying applications @@ -136,6 +137,12 @@ Some charms support more than one series. It is also possible to force a charm to deploy to a different series. See the documentation on [Multi-series charms][deploying-multi-series-charms] to learn more. +## Deploying a Kubernetes charm + +Kubernetes charms (`v.2.5.0`) can be deployed when the backing cloud is a +Kubernetes cluster. See page [Using Kubernetes with Juju][clouds-k8s] for an +overview. + ## Configuring at deployment time Deployed applications usually start with a sane default configuration. However, @@ -192,3 +199,4 @@ matter. [deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines [deploying-to-network-spaces]: ./charms-deploying-advanced.md#deploying-to-network-spaces [#exposing-deployed-applications]: #exposing-deployed-applications +[clouds-k8s]: ./clouds-k8s.md diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 86dc1136c..361a9be7d 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -51,39 +51,41 @@ be set up prior to the creation of the storage pool. See [Types of persistent volumes][upstream-kubernetes-volumes] for the list of Kubernetes supported backends. -#### Statically provisioned volumes +Static volumes are mainly intended for testing/prototyping. -You set up static volumes via storage class definitions. The -[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. Here is a example procedure: +#### Statically provisioned volumes + +You set up static volumes via YAML definition files. The +[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. +Here is a example procedure: ```bash sudo snap install --classic kubectl kubectl create -f charm-storage-vol1.yaml kubectl create -f operator-storage.yaml -kubectl describe pv ``` The example YAML-formatted files `operator-storage.yaml` and `charm-storage-vol1.yaml` define volumes for operator storage and charm storage respectively that get created by the `kubectl` command. -The content of the storage class definition files are given below. Typically -multiple charm storage volumes would be required. Note that operator storage -needs a minimum of 1024 MiB. +The content of the volume definition files are given below. Typically multiple +charm storage volumes would be required. Note that operator storage needs a +minimum of 1024 MiB. ^# charm-storage-vol1.yaml kind: PersistentVolume apiVersion: v1 metadata: - name: op1 + name: vol1 spec: capacity: - storage: 1032Mi + storage: 100Mi accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: k8s-model-juju-operator-storage + storageClassName: k8s-model-juju-unit-storage hostPath: path: "/mnt/data/vol1" @@ -92,14 +94,14 @@ needs a minimum of 1024 MiB. kind: PersistentVolume apiVersion: v1 metadata: - name: vol1 + name: op1 spec: capacity: - storage: 100Mi + storage: 1032Mi accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: k8s-model-juju-unit-storage + storageClassName: k8s-model-juju-operator-storage hostPath: path: "/mnt/data/op1" @@ -133,6 +135,12 @@ the `deploy` command. It is also this command that triggers the actual creation of the Kubernetes storage class when that storage class is referred to for the first time. + + The pool name for operator storage *must* be called 'operator-storage' while a pool name for charm storage is arbitrary. @@ -172,6 +180,9 @@ juju create-storage-pool operator-storage kubernetes \ storage-class=microk8s-hostpath ``` +For microk8s, a special storage class name of 'microk8s-hostpath' is always +used. + For LXD (statically provisioned): ```bash @@ -203,6 +214,14 @@ As with the operator storage static volume scenario, the final storage class name associated with pool 'k8s-pool', assuming a model of 'k8s-model', becomes 'k8s-model-juju-unit-storage'. +For `microk8s`, the only difference from the creation of the corresponding +operator storage pool is the pool name: + +```bash +juju create-storage-pool k8s-pool kubernetes \ + storage-class=microk8s-hostpath +``` + ### External storage and storage precedence rules Although the recommended approach is to use Juju-managed storage, Juju does @@ -229,9 +248,9 @@ For charm storage the rules are similar: - `default` 1. a storage class with label `storageclass.kubernetes.io/is-default-class` -Notice that for both operator and charm storage, the first two rules account -for Juju-managed statically provisioned volumes and dynamically provisioned -volumes, respectively. +Notice that for both operator and charm storage, the first two rules are +compatible with Juju-managed statically provisioned volumes and dynamically +provisioned volumes, respectively. diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 95670fc1e..3ae543071 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -8,7 +8,7 @@ TODO: Should eventually link to k8s-charm developer documentation # Using Kubernetes with Juju -Kubernetes provides a flexible architecture for managing containerised +Kubernetes ("k8s") provides a flexible architecture for managing containerised applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. @@ -16,7 +16,7 @@ most commonly employs Docker as its container technology. This page assumes you have a good understanding of [Persistent storage and Kubernetes][charms-storage-k8s]. -## Juju k8s-specific workflow +## Juju Kubernetes-specific workflow The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and `scale-application`. All other concepts and commands are applied in the @@ -53,7 +53,7 @@ Juju: 1. Add a model 1. Create persistent storage (if necessary) 1. Create storage pools (charm storage if necessary) - 1. Deploy a Kubernetes charm + 1. Deploy a Kubernetes charm or bundle ### Obtain a Kubernetes cluster @@ -177,6 +177,20 @@ kubectl create -f charm-storage-vol1.yaml kubectl create -f operator-storage.yaml ``` +We can inspect these new persistent volumes (PV): + +```bash +kubectl get sc,pv,pvc +``` + +Output: + +```no-highlight +NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE +persistentvolume/op1 1032Mi RWO Retain Available k8s-model-juju-operator-storage 25m +persistentvolume/vol1 100Mi RWO Retain Available k8s-model-juju-unit-storage 24m +``` + ### Create storage pools Create storage pools for operator storage and, if needed, charm storage. We @@ -191,19 +205,32 @@ juju create-storage-pool k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -### Deploy a Kubernetes charm +Notice how the model name 'k8s-model' got prefixed to the storage class names +we specified with the `create-storage-pool` commands. + +### Deploy a Kubernetes charm or bundle It's time to deploy a Kubernetes-specific charm. Our example uses a [MariaDB charm][charm-store-staging-mariadb-k8s] that will use the previously created charm storage called 'lxd-k8s-pool': ```bash -juju deploy cs:~wallyworld/mariadb-k8s --storage database=lxd-k8s-pool,10M +juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M ``` The [Using Juju storage][charms-storage-juju-deploy] page covers the above syntax. +Check for changes to PVs, PV "claims" (the requester of a PV), and storage +classes: + +```bash +kubectl -n k8s-model get pvc,pv,sc +``` + +See section [Kubernetes bundles][charms-bundles-k8s] if you're interested in +using bundles. + #### Configuration The below table lists configuration keys supported by Kubernetes charms that @@ -254,6 +281,7 @@ conjunction with the configured ingress controller (default: nginx). [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator [charms-storage-k8s]: ./charms-storage-k8s.md +[charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy [tutorial-microk8s]: ./tutorial-microk8s.md From d928b5003ba78ec0ed1f3e2ecbbc29cea5c927e2 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 22 Nov 2018 14:17:02 -0500 Subject: [PATCH 150/311] add scaling --- src/en/charms-scaling.md | 24 ++++++++++++++++++++++-- src/en/clouds-k8s.md | 6 +++--- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/src/en/charms-scaling.md b/src/en/charms-scaling.md index c114e7078..64ab6de7a 100644 --- a/src/en/charms-scaling.md +++ b/src/en/charms-scaling.md @@ -1,5 +1,6 @@ Title: Scaling applications TODO: More direction ito how users discover "built-in scaling" (e.g. the store is not clear on wordpress) + Write a tutorial on Kubernetes scaling # Scaling applications @@ -19,7 +20,8 @@ mention some less common situations. ## Scaling up In the context of Juju, scaling up means increasing the number of application -units and always involves the `add-unit` command. +units and always involves the `add-unit` command. The exception is for a +Kubernetes-backed cloud where the `scale-application` command is used. Closely resembling scaling up is the addition of a machine devoid of a unit. This is accomplished via the `add-machine` command: @@ -67,6 +69,15 @@ To add five more units (with each running in its own machine): juju add-unit -n 5 mediawiki ``` +### Scaling up within a Kubernetes model + +To scale up while in a Kubernetes model the total number of desired units for +the application is simply stated. Here we want a total of three units: + +```bash +juju scale-application mediawiki 3 +``` + ### Scaling up using a charm with built-in scaling Some charms have scaling built-in where scaling up really *is* as simple as @@ -152,7 +163,8 @@ constraints. ## Scaling down In the context of Juju, scaling down means decreasing the number of application -units and always involves the `remove-unit` command. +units and always involves the `remove-unit` command. The exception is for a +Kubernetes-backed cloud where the `scale-application` command is used. Closely resembling scaling down is the direct removal of a machine. This is therefore also covered here and is accomplished via the `remove-machine` @@ -182,6 +194,14 @@ juju remove-machine 6 For more information on removing applications and machines, see the [Removing Juju objects][charms-destroy] page. +### Scaling down within a Kubernetes model + +To scale down while in a Kubernetes model the total number of desired units for +the application is simply stated. Here we want a total of two units: + +```bash +juju scale-application mediawiki 2 +``` diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 3ae543071..c268a35d7 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -53,7 +53,7 @@ Juju: 1. Add a model 1. Create persistent storage (if necessary) 1. Create storage pools (charm storage if necessary) - 1. Deploy a Kubernetes charm or bundle + 1. Deploy a Kubernetes charm ### Obtain a Kubernetes cluster @@ -208,11 +208,11 @@ juju create-storage-pool k8s-pool kubernetes \ Notice how the model name 'k8s-model' got prefixed to the storage class names we specified with the `create-storage-pool` commands. -### Deploy a Kubernetes charm or bundle +### Deploy a Kubernetes charm It's time to deploy a Kubernetes-specific charm. Our example uses a [MariaDB charm][charm-store-staging-mariadb-k8s] that will use the previously -created charm storage called 'lxd-k8s-pool': +created charm storage called 'k8s-pool': ```bash juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M From fa032269e649e944c3a3f60177c0d6a94a588ee8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 22 Nov 2018 14:55:02 -0500 Subject: [PATCH 151/311] add --to placement directive --- src/en/charms-constraints.md | 5 +++++ src/en/charms-deploying-advanced.md | 8 ++++++++ src/en/reference-constraints.md | 5 +++-- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/src/en/charms-constraints.md b/src/en/charms-constraints.md index c974afce5..caa3c5bd2 100644 --- a/src/en/charms-constraints.md +++ b/src/en/charms-constraints.md @@ -49,6 +49,11 @@ LXD constraints also honour instance type names from either memory). When used in combination with specific CPU/MEM constraints the latter values will override corresponding instance type values. +### Constraints and Kubernetes + +Like LXD containers, constraints used within a Kubernetes model are treated as +maximums. + ## Constraint scopes, defaults, and precedence Constraints can be applied to various levels or scopes. Defaults can be set on diff --git a/src/en/charms-deploying-advanced.md b/src/en/charms-deploying-advanced.md index 662e7167e..359bad689 100644 --- a/src/en/charms-deploying-advanced.md +++ b/src/en/charms-deploying-advanced.md @@ -159,6 +159,14 @@ juju deploy mediawiki --to node1.maas juju deploy mariadb --to node1.lxd ``` +For a Kubernetes-backed cloud, a Kubernetes node can be targeted based on +matching labels. The label can be either built-in or one that is user-defined +and added to the node. For example: + +```bash +juju deploy mariadb-k8s --to kubernetes.io/hostname=somehost +``` + ### add-unit --to To add a unit of 'rabbitmq-server' to machine '1': diff --git a/src/en/reference-constraints.md b/src/en/reference-constraints.md index 25884ebb2..ebef4eb89 100644 --- a/src/en/reference-constraints.md +++ b/src/en/reference-constraints.md @@ -24,8 +24,9 @@ For in-depth coverage and examples see the Effective CPU cores. An integer. - `cpu-power` - Abstract CPU power. 100 units is roughly equivalent to "a single 2007-era - Xeon" as reflected by 1 Amazon vCPU. + Abstract CPU power. An integer, where 100 units is roughly equivalent to "a + single 2007-era Xeon" as reflected by 1 Amazon vCPU. In a Kubernetes + context a unit of "milli" is implied. **Note:** Not supported by all providers. Use `cores` for portability. From bf1dba6e0effdc74902de2ef518d5c3c3498c512 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 23 Nov 2018 20:47:32 -0500 Subject: [PATCH 152/311] updates --- src/en/clouds-k8s.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index c268a35d7..6f3ec6068 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -4,7 +4,8 @@ TODO: Should eventually link to k8s-charm developer documentation Consider manually adding a cluster via `add-cloud` and `add-credential` Change from staging store to production store when available Link to Discourse posts on aws-integrator? - Write another tutorial on building a cluster using the methods listed + Write tutorial on building a cluster using GKE + Write tutorial on building a cluster using AWS # Using Kubernetes with Juju @@ -59,19 +60,24 @@ Juju: You may obtain a Kubernetes cluster in any way. However, in this document, we deploy the cluster using Juju itself (with the 'localhost' cloud). We will do -so by deploying a minimal two-machine Kubernetes cluster by making use of the +so by deploying a minimal two-machine Kubernetes cluster with the use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash -juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost lxd-k8s +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost aws juju deploy kubernetes-core ``` -Sample output to `juju status` looks like this: +!!! Note: + We've used the staging Charm Store in these instructions as the standard + site does not yet support Kubernetes charms and bundles. + +This can take around 10 minutes to settle. Sample final output to `juju status` +looks like this: ```no-highlight Model Controller Cloud/Region Version SLA Timestamp -default lxd-k8s localhost/localhost 2.5-beta2 unsupported 22:22:14Z +default aws localhost/localhost 2.5-beta2 unsupported 22:22:14Z App Version Status Scale Charm Store Rev OS Notes easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu @@ -94,9 +100,7 @@ Machine State DNS Inst id Series AZ Message 1 started 10.234.141.32 juju-7c937e-1 bionic Running ``` -!!! Note: - We've used the staging Charm Store in these instructions as the standard - site does not yet support Kubernetes charms and bundles. +Please wait to get very similar output before proceeding. #### Alternative methods for obtaining a Kubernetes cluster @@ -143,7 +147,7 @@ juju scp kubernetes-master/0:config ~/.kube/config We can now take advantage of the `add-k8s` command as it internally parses the copied configuration file from the specified path. This allows us to quickly -add the cluster-cloud, which we have arbitrarily called 'lxd-k8s-cloud': +add the cluster-cloud, which we have arbitrarily called 'k8s-cloud': ```bash juju add-k8s k8s-cloud @@ -151,6 +155,13 @@ juju add-k8s k8s-cloud Now confirm the successful addition of the cloud with the `clouds` command. +Before continuing, ensure the output to the following command does not report +anything suspicious: + +```bash +kubectl describe pods +``` + ### Add a model Add a model in the usual way: @@ -169,8 +180,8 @@ cloud's storage is not supported natively by Kubernetes. You will need to do the same for charm storage if your charm has storage requirements (we will do so since our intended charm will need storage). -Here, since our example is using an unsupported storage solution (LXD) we'll -create static volumes for both types: +Since our example scenario is using an unsupported storage solution (LXD) we'll +need to create static volumes for both types: ```bash kubectl create -f charm-storage-vol1.yaml @@ -205,8 +216,9 @@ juju create-storage-pool k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -Notice how the model name 'k8s-model' got prefixed to the storage class names -we specified with the `create-storage-pool` commands. +Notice how the model name 'k8s-model' is not part of the storage class names +that show up for each static volume above. Juju will prepend the current model +when a provisioner of 'kubernetes.io/no-provisioner' is requested. ### Deploy a Kubernetes charm From 86c5270862f68a8e6668d62e1f0f6156bad403ca Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 23 Nov 2018 21:09:50 -0500 Subject: [PATCH 153/311] remove old maas manual page; lighten up top of clouds page --- src/en/clouds-maas-manual.md | 69 ------------------------------------ src/en/clouds-maas.md | 1 - src/en/clouds.md | 24 ++++++------- 3 files changed, 12 insertions(+), 82 deletions(-) delete mode 100644 src/en/clouds-maas-manual.md diff --git a/src/en/clouds-maas-manual.md b/src/en/clouds-maas-manual.md deleted file mode 100644 index 80bb621eb..000000000 --- a/src/en/clouds-maas-manual.md +++ /dev/null @@ -1,69 +0,0 @@ -Title: Manually adding MAAS clouds - -# Manually adding MAAS clouds - -A MAAS cloud may be registered with Juju using the interactive `add-cloud` -command (see [Using MAAS with Juju][clouds-maas]) but it is also possible to do -so using a YAML file. All that varies is the endpoint and the name, since they -use the same authentication method. Here is an example: - -```yaml -clouds: - devmaas: - type: maas - auth-types: [oauth1] - endpoint: http://devmaas/MAAS - testmaas: - type: maas - auth-types: [oauth1] - endpoint: http://172.18.42.10/MAAS - prodmaas: - type: maas - auth-types: [oauth1] - endpoint: http://prodmaas/MAAS -``` - -This example YAML defines three MAAS (region) controllers. To add a MAAS cloud -from this definition to Juju, run the command in the form: - -```bash -juju add-cloud -``` - -To add two MAAS clouds from the above example we would run: - -```bash -juju add-cloud devmaas maas-clouds.yaml -juju add-cloud prodmaas maas-clouds.yaml -``` - -Where the supplied cloud names refer to those in the YAML file. - -This will add both the 'prodmaas' and 'devmaas' clouds, which you can confirm -by running: - -```bash -juju list-clouds -``` - -This will list the newly added clouds: - - - -```no-highlight -Cloud Regions Default Type Description -aws 11 us-east-1 ec2 Amazon Web Services -... -devmaas 0 maas Metal As A Service -prodmaas 0 maas Metal As A Service -testmaas 0 maas Metal As A Service -``` - -It is necessary to add credentials for these clouds before bootstrapping them. -See the [Documentation on MAAS credentials here][maas-credentials]. - - - - -[clouds-maas]: ./clouds-maas.md -[maas-credentials]: ./clouds-maas.md#add-credentials diff --git a/src/en/clouds-maas.md b/src/en/clouds-maas.md index 9c7ac2998..26744ac43 100644 --- a/src/en/clouds-maas.md +++ b/src/en/clouds-maas.md @@ -170,7 +170,6 @@ See these pages for ideas on what to do next: [upstream-maas]: https://maas.io [maas-cli]: https://docs.ubuntu.com/maas/en/manage-cli [maas-api]: https://docs.ubuntu.com/maas/en/manage-account#api-key -[maas-manual]: ./clouds-maas-manual.md [create-a-controller-with-constraints]: ./controllers-creating.md#create-a-controller-with-constraints [models]: ./models.md [charms]: ./charms.md diff --git a/src/en/clouds.md b/src/en/clouds.md index 5fcf426e6..e10f6db40 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -8,11 +8,8 @@ table_of_contents: True # Clouds Juju supports a wide variety of clouds. In addition, many of these are known to -Juju out of the box. They are Amazon AWS, Microsoft Azure, Google GCE, Oracle -OCI, Rackspace, Joyent, and LXD. - -The remaining supported clouds do need to be added to Juju, and, as will be -shown, it is simply done. They are VMware vSphere, OpenStack, MAAS, and Manual. +Juju out of the box. The remaining supported clouds do need to be added to +Juju, and, as will be shown, it is simply done. Once your cloud is known to Juju, whether by default or due to it being added, the next step is to add your cloud credentials to Juju. The exception is for a @@ -21,18 +18,21 @@ local LXD cloud; credentials are added automatically. This rest of this page covers general cloud management and an overview of how clouds are added. You can still get started by selecting your cloud here: - - [Amazon AWS][clouds-aws] - - [Microsoft Azure][clouds-azure] - - [Google GCE][clouds-google] - - [Oracle OCI][clouds-oci] - - [Rackspace][clouds-rackspace] - - [Joyent][clouds-joyent] - - [LXD][clouds-lxd] + - [Amazon AWS][clouds-aws] ***** + - [Microsoft Azure][clouds-azure] ***** + - [Google GCE][clouds-google] ***** + - [Oracle][clouds-oci] ***** + - [Rackspace][clouds-rackspace] ***** + - [Joyent][clouds-joyent] ***** + - [LXD][clouds-lxd] (local) ***** + - [LXD][clouds-lxd] (remote) - [VMware vSphere][clouds-vmware] - [OpenStack][clouds-openstack] - [MAAS][clouds-maas] - [Manual][clouds-manual] +Those clouds known to Juju out of the box are denoted by an *****. + ## General cloud management To get the list of clouds that Juju is currently aware of use the `clouds` From 6dbe3963e0d78528c605650d398fac3abf7906da Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 23 Nov 2018 21:40:41 -0500 Subject: [PATCH 154/311] oci replacements --- src/en/clouds-lxd-advanced.md | 2 -- src/en/clouds-maas.md | 2 +- src/en/clouds-manual.md | 2 +- src/en/clouds.md | 2 +- src/en/help-openstack.md | 2 -- src/en/help-vmware.md | 2 +- src/en/tut-google.md | 24 ++++++++++++------------ 7 files changed, 16 insertions(+), 20 deletions(-) diff --git a/src/en/clouds-lxd-advanced.md b/src/en/clouds-lxd-advanced.md index 3c5b41461..fa6df4323 100644 --- a/src/en/clouds-lxd-advanced.md +++ b/src/en/clouds-lxd-advanced.md @@ -72,9 +72,7 @@ Cloud Types lxd maas manual - oci openstack - oracle vsphere Select cloud type: lxd diff --git a/src/en/clouds-maas.md b/src/en/clouds-maas.md index 26744ac43..2178526dd 100644 --- a/src/en/clouds-maas.md +++ b/src/en/clouds-maas.md @@ -26,10 +26,10 @@ Example user session: ```no-highlight Cloud Types + lxd maas manual openstack - oracle vsphere Select cloud type: maas diff --git a/src/en/clouds-manual.md b/src/en/clouds-manual.md index 5894a41bf..5d8786dfa 100644 --- a/src/en/clouds-manual.md +++ b/src/en/clouds-manual.md @@ -75,10 +75,10 @@ Example user session: ```no-highlight Cloud Types + lxd maas manual openstack - oracle vsphere Select cloud type: manual diff --git a/src/en/clouds.md b/src/en/clouds.md index e10f6db40..b92f84c46 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -21,7 +21,7 @@ clouds are added. You can still get started by selecting your cloud here: - [Amazon AWS][clouds-aws] ***** - [Microsoft Azure][clouds-azure] ***** - [Google GCE][clouds-google] ***** - - [Oracle][clouds-oci] ***** + - [Oracle OCI][clouds-oci] ***** - [Rackspace][clouds-rackspace] ***** - [Joyent][clouds-joyent] ***** - [LXD][clouds-lxd] (local) ***** diff --git a/src/en/help-openstack.md b/src/en/help-openstack.md index cf49d1085..ec06a60ae 100644 --- a/src/en/help-openstack.md +++ b/src/en/help-openstack.md @@ -46,9 +46,7 @@ Cloud Types lxd maas manual - oci openstack - oracle vsphere Select cloud type: openstack diff --git a/src/en/help-vmware.md b/src/en/help-vmware.md index 35c0f0b95..75489340f 100644 --- a/src/en/help-vmware.md +++ b/src/en/help-vmware.md @@ -28,10 +28,10 @@ Example user session: ```no-highlight Cloud Types + lxd maas manual openstack - oracle vsphere Select cloud type: vsphere diff --git a/src/en/tut-google.md b/src/en/tut-google.md index 1c3ee6620..0a7aa3c07 100644 --- a/src/en/tut-google.md +++ b/src/en/tut-google.md @@ -30,18 +30,18 @@ First, install Juju, if you have not done so already. See Type `juju clouds` and you'll see output very similar to the following: ```bash -Cloud Regions Default Type Description -aws 14 us-east-1 ec2 Amazon Web Services -aws-china 1 cn-north-1 ec2 Amazon China -aws-gov 1 us-gov-west-1 ec2 Amazon (USA Government) -azure 26 centralus azure Microsoft Azure -azure-china 2 chinaeast azure Microsoft Azure China -cloudsigma 5 hnl cloudsigma CloudSigma Cloud -google 9 us-east1 gce Google Cloud Platform -joyent 6 eu-ams-1 joyent Joyent Cloud -oracle 5 uscom-central-1 oracle Oracle Compute Cloud Service -rackspace 6 dfw rackspace Rackspace Cloud -localhost 1 localhost lxd LXD Container Hypervisor +Cloud Regions Default Type Description +aws 15 us-east-1 ec2 Amazon Web Services +aws-china 1 cn-north-1 ec2 Amazon China +aws-gov 1 us-gov-west-1 ec2 Amazon (USA Government) +azure 26 centralus azure Microsoft Azure +azure-china 2 chinaeast azure Microsoft Azure China +cloudsigma 5 hnl cloudsigma CloudSigma Cloud +google 13 us-east1 gce Google Cloud Platform +joyent 6 eu-ams-1 joyent Joyent Cloud +oracle 4 us-phoenix-1 oci Oracle Cloud Infrastructure +rackspace 6 dfw rackspace Rackspace Cloud +localhost 1 localhost lxd LXD Container Hypervisor ``` As mentioned, we're going with Google's Cloud Engine, which we'll From 79e4365209ad2c691ac18ec913e5eca899050d25 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 26 Nov 2018 18:54:09 -0500 Subject: [PATCH 155/311] details --- src/en/charms-storage-k8s.md | 20 ++++---- src/en/clouds-k8s.md | 99 +++++++++++++++++++++++------------- src/en/tutorial-microk8s.md | 18 +++---- 3 files changed, 82 insertions(+), 55 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 361a9be7d..6a34cd813 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -73,37 +73,37 @@ The content of the volume definition files are given below. Typically multiple charm storage volumes would be required. Note that operator storage needs a minimum of 1024 MiB. -^# charm-storage-vol1.yaml +^# operator-storage.yaml kind: PersistentVolume apiVersion: v1 metadata: - name: vol1 + name: op1 spec: capacity: - storage: 100Mi + storage: 1032Mi accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: k8s-model-juju-unit-storage + storageClassName: k8s-model-juju-operator-storage hostPath: - path: "/mnt/data/vol1" + path: "/mnt/data/op1" -^# operator-storage.yaml +^# charm-storage-vol1.yaml kind: PersistentVolume apiVersion: v1 metadata: - name: op1 + name: vol1 spec: capacity: - storage: 1032Mi + storage: 100Mi accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain - storageClassName: k8s-model-juju-operator-storage + storageClassName: k8s-model-juju-unit-storage hostPath: - path: "/mnt/data/op1" + path: "/mnt/data/vol1" !!! Important: The storage class name for a statically provisioned volume must be prefixed diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 6f3ec6068..edf3bcc26 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -6,6 +6,7 @@ TODO: Should eventually link to k8s-charm developer documentation Link to Discourse posts on aws-integrator? Write tutorial on building a cluster using GKE Write tutorial on building a cluster using AWS + Example done with AWS since a LXD bundle needs each of its charms to specify profile edits according to https://is.gd/dqXGN2 # Using Kubernetes with Juju @@ -59,12 +60,12 @@ Juju: ### Obtain a Kubernetes cluster You may obtain a Kubernetes cluster in any way. However, in this document, we -deploy the cluster using Juju itself (with the 'localhost' cloud). We will do +deploy the cluster using Juju itself (with the 'aws' cloud). We will do so by deploying a minimal two-machine Kubernetes cluster with the use of the [kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: ```bash -juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore localhost aws +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore aws aws juju deploy kubernetes-core ``` @@ -76,28 +77,28 @@ This can take around 10 minutes to settle. Sample final output to `juju status` looks like this: ```no-highlight -Model Controller Cloud/Region Version SLA Timestamp -default aws localhost/localhost 2.5-beta2 unsupported 22:22:14Z +Model Controller Cloud/Region Version SLA Timestamp +default aws aws/us-east-1 2.5-beta2 unsupported 19:31:40Z -App Version Status Scale Charm Store Rev OS Notes -easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu -etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu -flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu -kubernetes-master 1.12.2 waiting 1 kubernetes-master jujucharms 219 ubuntu exposed -kubernetes-worker 1.12.2 waiting 1 kubernetes-worker jujucharms 239 ubuntu exposed +App Version Status Scale Charm Store Rev OS Notes +easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu +etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu +flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu +kubernetes-master 1.12.2 active 1 kubernetes-master jujucharms 219 ubuntu exposed +kubernetes-worker 1.12.2 active 1 kubernetes-worker jujucharms 239 ubuntu exposed Unit Workload Agent Machine Public address Ports Message -easyrsa/0* active idle 0/lxd/0 10.10.19.148 Certificate Authority connected. -etcd/0* active idle 0 10.234.141.194 2379/tcp Healthy with 1 known peer -kubernetes-master/0* waiting idle 0 10.234.141.194 6443/tcp Waiting for kube-system pods to start - flannel/0* active idle 10.234.141.194 Flannel subnet 10.1.45.1/24 -kubernetes-worker/0* waiting idle 1 10.234.141.32 80/tcp,443/tcp Waiting for kubelet to start. - flannel/1 active idle 10.234.141.32 Flannel subnet 10.1.37.1/24 - -Machine State DNS Inst id Series AZ Message -0 started 10.234.141.194 juju-7c937e-0 bionic Running -0/lxd/0 started 10.10.19.148 juju-7c937e-0-lxd-0 bionic Container started -1 started 10.234.141.32 juju-7c937e-1 bionic Running +easyrsa/0* active idle 0/lxd/0 10.213.7.167 Certificate Authority connected. +etcd/0* active idle 0 54.162.110.147 2379/tcp Healthy with 1 known peer +kubernetes-master/0* active idle 0 54.162.110.147 6443/tcp Kubernetes master running. + flannel/0* active idle 54.162.110.147 Flannel subnet 10.1.81.1/24 +kubernetes-worker/0* active idle 1 18.210.11.210 80/tcp,443/tcp Kubernetes worker running. + flannel/1 active idle 18.210.11.210 Flannel subnet 10.1.34.1/24 + +Machine State DNS Inst id Series AZ Message +0 started 54.162.110.147 i-0f94dff8233b92b3c bionic us-east-1a running +0/lxd/0 started 10.213.7.167 juju-2f253d-0-lxd-0 bionic us-east-1a Container started +1 started 18.210.11.210 i-0a2b626f2b0c92219 bionic us-east-1b running ``` Please wait to get very similar output before proceeding. @@ -114,16 +115,15 @@ cluster: for guidance. Although the tutorial specifically mentions the [Canonical Distribution of Kubernetes][cdk-charm] you can choose the identical minimal install deployed above from the installer's interface. - 1. Use [`microk8s`][upstream-microk8s]. With microk8s, you get a local, fully - compliant Kubernetes deployment with dynamic persistent volume support. See - tutorial [Using Juju with microk8s][tutorial-microk8s]. + 1. Use [MicroK8s][upstream-microk8s] where you get a local, fully compliant + Kubernetes deployment with dynamic persistent volume support. See tutorial + [Using Juju with microk8s][tutorial-microk8s]. 1. Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. 1. Use a public cloud vendor such as [Amazon EKS][upstream-eks-kubernetes], - [Azure AKS][upstream-aks-kubernetes], - [Google GKE][upstream-gke-kubernetes], and - [DigitalOcean Kubernetes][upstream-dok-kubernetes]. + [Azure AKS][upstream-aks-kubernetes], and + [Google GKE][upstream-gke-kubernetes]. ### Add the cluster to Juju @@ -184,14 +184,15 @@ Since our example scenario is using an unsupported storage solution (LXD) we'll need to create static volumes for both types: ```bash -kubectl create -f charm-storage-vol1.yaml kubectl create -f operator-storage.yaml +kubectl create -f charm-storage-vol1.yaml ``` -We can inspect these new persistent volumes (PV): +We can inspect these new persistent volumes (PV) and any possible storage +classes (SC): ```bash -kubectl get sc,pv,pvc +kubectl get sc,pv ``` Output: @@ -233,15 +234,42 @@ juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M The [Using Juju storage][charms-storage-juju-deploy] page covers the above syntax. -Check for changes to PVs, PV "claims" (the requester of a PV), and storage -classes: +The output to the `status` command should resemble this: + +```no-highlight +Model Controller Cloud/Region Version SLA Timestamp +k8s-model aws k8s-cloud 2.5-beta2 unsupported 20:52:11Z + +App Version Status Scale Charm Store Rev OS Address Notes +mariadb-k8s active 1 mariadb-k8s jujucharms 13 kubernetes 10.152.183.82 + +Unit Workload Agent Address Ports Message +mariadb-k8s/0* active idle 10.1.34.13 3306/TCP +``` + +Check for changes to the cluster storage objects: ```bash -kubectl -n k8s-model get pvc,pv,sc +kubectl -n k8s-model get sc,pv ``` -See section [Kubernetes bundles][charms-bundles-k8s] if you're interested in -using bundles. +Sample output: + +```no-highlight +NAME PROVISIONER AGE +storageclass.storage.k8s.io/k8s-model-juju-operator-storage kubernetes.io/no-provisioner 2m16s +storageclass.storage.k8s.io/k8s-model-juju-unit-storage kubernetes.io/no-provisioner 115s + +NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE +persistentvolume/op1 1032Mi RWO Retain Bound k8s-model/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 k8s-model-juju-operator-storage 25m +persistentvolume/vol1 100Mi RWO Retain Bound k8s-model/juju-database-0-juju-mariadb-k8s-0 k8s-model-juju-unit-storage 25m +``` + +We see the storage classes that we specified in the YAML files are now in use +and the persistent volumes have a claim on them. + +Section [Kubernetes bundles][charms-bundles-k8s] has some extra information on +bundles if that's what you're interested in. #### Configuration @@ -301,5 +329,4 @@ conjunction with the configured ingress controller (default: nginx). [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ [upstream-gke-kubernetes]: https://cloud.google.com/kubernetes-engine/ -[upstream-dok-kubernetes]: https://www.digitalocean.com/products/kubernetes/ [upstream-microk8s]: https://microk8s.io diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index 6d8d56edb..f9b4a9b38 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -1,7 +1,7 @@ -Title: Using Juju with microk8s +Title: Using Juju with MicroK8s TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1804495 -# Using Juju with microk8s +# Using Juju with MicroK8s *This is in connection to the topic of [Using Kubernetes with Juju][clouds-k8s]. See that resource for background @@ -14,14 +14,14 @@ services natively (i.e. no virtual machines or containers), and is fully [CNCF certified][upstream-cncf]. This option is perfect for testing Kubernetes on your laptop. Using it with Juju is icing on the cake! -Since microk8s runs locally we'll be using a local LXD cloud to create a Juju +Since MicroK8s runs locally we'll be using a local LXD cloud to create a Juju controller. ## Installing the software These instructions assume that you're using a fresh Ubuntu 18.04 LTS install, or at least one that is not already using either Juju or LXD. This tutorial -installs Juju, LXD, and microk8s as snaps. It also removes a possibly existing +installs Juju, LXD, and MicroK8s as snaps. It also removes a possibly existing LXD deb package. Do not invoke the purge command below if you're currently using LXD! @@ -32,7 +32,7 @@ sudo snap install microk8s --classic sudo apt purge -y liblxc1 lxcfs lxd lxd-client ``` -Enable some microk8s addons that will provide DNS and storage class support: +Enable some MicroK8s addons that will provide DNS and storage class support: ```bash microk8s.enable dns storage @@ -121,7 +121,7 @@ k8s-model* microk8s-cloud available 0 admin never connected ## Adding storage -One of the benefits of using `microk8s` is that we get dynamically provisioned +One of the benefits of using MicroK8s is that we get dynamically provisioned storage out of the box. Below we have Juju create two storage pools, one for operator storage and one for charm storage: @@ -206,7 +206,7 @@ cluster information. ## Removing configuration and software -To remove all traces of microk8s and its configuration follow these steps: +To remove all traces of MicroK8s and its configuration follow these steps: ```bash juju destroy-model -y --destroy-storage k8s-model @@ -228,9 +228,9 @@ That's the end of this tutorial! ## Next steps -For more experience with a standalone (non-Juju) microk8s installation you can +For more experience with a standalone (non-Juju) MicroK8s installation you can go through Ubuntu tutorial -[Install a local Kubernetes with microk8s][ubuntu-tutorial_kubernetes-microk8s]. +[Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. From dc9fc063f2b1a79bcb0a9f2180831c48d38d6fad Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 27 Nov 2018 11:28:14 -0500 Subject: [PATCH 156/311] refactor due to problem with lxd deployments --- src/en/charms-storage-k8s.md | 2 +- src/en/clouds-k8s.md | 208 +++++++++++------------------------ 2 files changed, 67 insertions(+), 143 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 6a34cd813..de0cf86c7 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -118,7 +118,7 @@ Once a static volume is used, it is never re-used, even if the unit/pod is terminated and the volume is released. Just as static volumes are manually created, they must also be manually removed. -### Creating storage pools +### Storage pool creation Juju storage pools are created for both operator storage and charm storage using the `create-storage-pool` command. Both are done by mapping to either a diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index edf3bcc26..a5f805c1d 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -15,8 +15,9 @@ applications at scale (see the [Kubernetes documentation][upstream-kubernetes-docs] for more information). It most commonly employs Docker as its container technology. -This page assumes you have a good understanding of -[Persistent storage and Kubernetes][charms-storage-k8s]. +These instructions refer to page +[Persistent storage and Kubernetes][charms-storage-k8s] in a few places. You +may want to familiarise yourself with it now. ## Juju Kubernetes-specific workflow @@ -24,11 +25,10 @@ The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and `scale-application`. All other concepts and commands are applied in the traditional Juju manner. -If the Kubernetes cluster is built with Juju itself (via a bundle) and -`juju add-k8s` is run immediately afterwards, the contents of file -`~/.kube/config` (if it exists) is used to add the cluster and the credentials -to Juju, making the usual combination of `add-cloud` and `add-credential` -unnecessary. +The `add-k8s` command is used to add the Kubernetes cluster to Juju's list of +known clouds and import its credentials. The cluster configuration file will +first need to be copied to `~/.kube/config`. This command makes the usual +combination of `add-cloud` and `add-credential` unnecessary. User credentials can still be added by way of the `add-credential` or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used to @@ -39,8 +39,6 @@ long as the contents of the configuration file has been changed accordingly. The KUBECONFIG environment variable is useful here as it will be honoured by Juju when finding the file to load. -We'll demonstrate the use of the `add-k8s` command below. - ## Using Kubernetes with Juju First off, a Kubernetes cluster will be required. Essentially, you will use it @@ -54,77 +52,39 @@ Juju: 1. Add the cluster to Juju 1. Add a model 1. Create persistent storage (if necessary) - 1. Create storage pools (charm storage if necessary) + 1. Create operator storage pool + 1. Create charm storage pool (if necessary) 1. Deploy a Kubernetes charm ### Obtain a Kubernetes cluster -You may obtain a Kubernetes cluster in any way. However, in this document, we -deploy the cluster using Juju itself (with the 'aws' cloud). We will do -so by deploying a minimal two-machine Kubernetes cluster with the use of the -[kubernetes-core][kubernetes-core-charm] bundle available in the Charm Store: +There are many ways you may obtain a Kubernetes cluster. Here is a list of +suggestions: -```bash -juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore aws aws -juju deploy kubernetes-core -``` - -!!! Note: - We've used the staging Charm Store in these instructions as the standard - site does not yet support Kubernetes charms and bundles. - -This can take around 10 minutes to settle. Sample final output to `juju status` -looks like this: - -```no-highlight -Model Controller Cloud/Region Version SLA Timestamp -default aws aws/us-east-1 2.5-beta2 unsupported 19:31:40Z - -App Version Status Scale Charm Store Rev OS Notes -easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu -etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu -flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu -kubernetes-master 1.12.2 active 1 kubernetes-master jujucharms 219 ubuntu exposed -kubernetes-worker 1.12.2 active 1 kubernetes-worker jujucharms 239 ubuntu exposed - -Unit Workload Agent Machine Public address Ports Message -easyrsa/0* active idle 0/lxd/0 10.213.7.167 Certificate Authority connected. -etcd/0* active idle 0 54.162.110.147 2379/tcp Healthy with 1 known peer -kubernetes-master/0* active idle 0 54.162.110.147 6443/tcp Kubernetes master running. - flannel/0* active idle 54.162.110.147 Flannel subnet 10.1.81.1/24 -kubernetes-worker/0* active idle 1 18.210.11.210 80/tcp,443/tcp Kubernetes worker running. - flannel/1 active idle 18.210.11.210 Flannel subnet 10.1.34.1/24 - -Machine State DNS Inst id Series AZ Message -0 started 54.162.110.147 i-0f94dff8233b92b3c bionic us-east-1a running -0/lxd/0 started 10.213.7.167 juju-2f253d-0-lxd-0 bionic us-east-1a Container started -1 started 18.210.11.210 i-0a2b626f2b0c92219 bionic us-east-1b running -``` - -Please wait to get very similar output before proceeding. - -#### Alternative methods for obtaining a Kubernetes cluster - -Here is a list of alternative methods to explore for setting up a Kubernetes -cluster: - - 1. Use the 'canonical-kubernetes' bundle, which is a more sophisticated + 1. Use the [kubernetes-core][kubernetes-core-charm] bundle, which gives a + minimal two-machine cluster available in the Charm Store. + 1. Use the [canonical-kubernetes][kubernetes-cdk-charm] bundle. This is the + Canonical Distribution of Kubernetes (CDK), which is a more sophisticated version of what we used above. - 1. Use the [`conjure-up`][upstream-conjure-up] installer. See Ubuntu tutorial + 1. Use the [conjure-up][upstream-conjure-up] installer. See Ubuntu tutorial [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] - for guidance. Although the tutorial specifically mentions the - [Canonical Distribution of Kubernetes][cdk-charm] you can choose the - identical minimal install deployed above from the installer's interface. + for guidance. Although the tutorial specifically mentions the CDK bundle + you can choose the core bundle from the installer's interface. 1. Use [MicroK8s][upstream-microk8s] where you get a local, fully compliant Kubernetes deployment with dynamic persistent volume support. See tutorial [Using Juju with microk8s][tutorial-microk8s]. 1. Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. - 1. Use a public cloud vendor such as [Amazon EKS][upstream-eks-kubernetes], + 1. Use a public Kubernetes vendor such as + [Amazon EKS][upstream-eks-kubernetes], [Azure AKS][upstream-aks-kubernetes], and [Google GKE][upstream-gke-kubernetes]. +!!! Note: + Kubernetes bundles do not work well on a LXD cloud at this time. Refer to + [Deploying on LXD][kubernetes-deploying-on-lxd] for details. + ### Add the cluster to Juju We will need some information about the cluster in order to add it to Juju. @@ -134,11 +94,9 @@ This is found within the main Kubernetes configuration file. If `conjure-up` was used to install the cluster then the rest of this section can be skipped; this install method adds the cluster for you. -#### Adding a juju-deployed cluster quickly - -If Juju was used to deploy the cluster, as we've done in this example, the -above file can be copied over from the Kubernetes master node (and saved as -`~/.kube/config`) in this way: +The configuration file can be copied over from the Kubernetes master node (and +saved as `~/.kube/config`). Here is one way you can do this if Juju was used to +install the cluster: ```bash mkdir ~/.kube @@ -155,16 +113,9 @@ juju add-k8s k8s-cloud Now confirm the successful addition of the cloud with the `clouds` command. -Before continuing, ensure the output to the following command does not report -anything suspicious: - -```bash -kubectl describe pods -``` - ### Add a model -Add a model in the usual way: +Add a model in the usual way. We've arbitrarily called it 'k8s-model': ```bash juju add-model k8s-model k8s-cloud @@ -173,40 +124,29 @@ juju add-model k8s-model k8s-cloud This will cause a Kubernetes namespace in the cluster to be created that will host all of the pods and other resources for that model. +!!! Note: + We've reused the model name of 'k8s-model' elsewhere on this page. Replace + it with your own model name. + ### Create persistent storage Create persistent static volumes for operator storage if your chosen backing cloud's storage is not supported natively by Kubernetes. You will need to do -the same for charm storage if your charm has storage requirements (we will do -so since our intended charm will need storage). - -Since our example scenario is using an unsupported storage solution (LXD) we'll -need to create static volumes for both types: +the same for charm storage if your charm has storage requirements. Here, we +show examples for creating static volumes for both types: ```bash kubectl create -f operator-storage.yaml kubectl create -f charm-storage-vol1.yaml ``` -We can inspect these new persistent volumes (PV) and any possible storage -classes (SC): - -```bash -kubectl get sc,pv -``` - -Output: - -```no-highlight -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -persistentvolume/op1 1032Mi RWO Retain Available k8s-model-juju-operator-storage 25m -persistentvolume/vol1 100Mi RWO Retain Available k8s-model-juju-unit-storage 24m -``` +For assistance with the contents of these files see section +[Statically provisioned volumes][charms-storage-k8s-static-pv]. ### Create storage pools Create storage pools for operator storage and, if needed, charm storage. We -will need to do both for our example: +show examples for creating pools of both types: ```bash juju create-storage-pool operator-storage kubernetes \ @@ -217,15 +157,15 @@ juju create-storage-pool k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -Notice how the model name 'k8s-model' is not part of the storage class names -that show up for each static volume above. Juju will prepend the current model -when a provisioner of 'kubernetes.io/no-provisioner' is requested. +For details on creating storage pools see section +[Storage pool creation][charms-storage-k8s-pool-creation]. ### Deploy a Kubernetes charm -It's time to deploy a Kubernetes-specific charm. Our example uses a -[MariaDB charm][charm-store-staging-mariadb-k8s] that will use the previously -created charm storage called 'k8s-pool': +A Kubernetes-specific charm is deployed in standard fashion. If the charm has +storage requirements you will need to specify them, as you do with a normal +charm. For example, here is a charm that uses the previously created charm +storage called 'k8s-pool': ```bash juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M @@ -234,42 +174,8 @@ juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M The [Using Juju storage][charms-storage-juju-deploy] page covers the above syntax. -The output to the `status` command should resemble this: - -```no-highlight -Model Controller Cloud/Region Version SLA Timestamp -k8s-model aws k8s-cloud 2.5-beta2 unsupported 20:52:11Z - -App Version Status Scale Charm Store Rev OS Address Notes -mariadb-k8s active 1 mariadb-k8s jujucharms 13 kubernetes 10.152.183.82 - -Unit Workload Agent Address Ports Message -mariadb-k8s/0* active idle 10.1.34.13 3306/TCP -``` - -Check for changes to the cluster storage objects: - -```bash -kubectl -n k8s-model get sc,pv -``` - -Sample output: - -```no-highlight -NAME PROVISIONER AGE -storageclass.storage.k8s.io/k8s-model-juju-operator-storage kubernetes.io/no-provisioner 2m16s -storageclass.storage.k8s.io/k8s-model-juju-unit-storage kubernetes.io/no-provisioner 115s - -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -persistentvolume/op1 1032Mi RWO Retain Bound k8s-model/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 k8s-model-juju-operator-storage 25m -persistentvolume/vol1 100Mi RWO Retain Bound k8s-model/juju-database-0-juju-mariadb-k8s-0 k8s-model-juju-unit-storage 25m -``` - -We see the storage classes that we specified in the YAML files are now in use -and the persistent volumes have a claim on them. - -Section [Kubernetes bundles][charms-bundles-k8s] has some extra information on -bundles if that's what you're interested in. +If you want to deploy a Kubernetes bundles see section +[Kubernetes bundles][charms-bundles-k8s]. #### Configuration @@ -309,22 +215,40 @@ Keys 'juju-external-hostname' and 'juju-application-path' control how the application is exposed externally using a Kubernetes Ingress Resource in conjunction with the configured ingress controller (default: nginx). +## Inspect cluster storage objects + +List cluster storage objects such as storage classes (SC), persistent +volumes (PV), and persistent volume claims (PVC) in this way: + +```bash +kubectl -n k8s-model get sc,pv,pvc +``` + +Drill down into Kubernetes objects such as pods and PVCs with the following +commands: + +```bash +kubectl -n k8s-model describe pods +kubectl -n k8s-model describe pvc +``` + [kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 -[cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ +[kubernetes-cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [upstream-kubernetes-docs]: https://kubernetes.io/docs [upstream-kubernetes-docs-service]: https://kubernetes.io/docs/concepts/services-networking/service/ [upstream-kubernetes-docs-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator -[charms-storage-k8s]: ./charms-storage-k8s.md +[charms-storage-k8s-static-pv]: ./charms-storage-k8s.md#statically-provisioned-volumes +[charms-storage-k8s-pool-creation]: ./charms-storage-k8s.md#storage-pool-creation [charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles -[charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy [tutorial-microk8s]: ./tutorial-microk8s.md +[kubernetes-deploying-on-lxd]: https://github.com/juju-solutions/bundle-canonical-kubernetes/wiki/Deploying-on-LXD [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ From 76ad070e679ad944788bfa101cbb6673a3ba130b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 27 Nov 2018 14:49:35 -0500 Subject: [PATCH 157/311] trivial --- src/en/clouds-k8s.md | 58 +++++++++++++++++++++---------------- src/en/tutorial-microk8s.md | 10 +++---- 2 files changed, 38 insertions(+), 30 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index a5f805c1d..1c2e2ac7f 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -39,6 +39,12 @@ long as the contents of the configuration file has been changed accordingly. The KUBECONFIG environment variable is useful here as it will be honoured by Juju when finding the file to load. +The `remove-k8s` command is used to remove a Kubernetes cluster from Juju's +list of known clouds. + +The `scale-application` command is used to scale a Kubernetes cluster. The +`add-unit` and `remove-unit` commands cannot be applied to a Kubernetes model. + ## Using Kubernetes with Juju First off, a Kubernetes cluster will be required. Essentially, you will use it @@ -52,34 +58,33 @@ Juju: 1. Add the cluster to Juju 1. Add a model 1. Create persistent storage (if necessary) - 1. Create operator storage pool - 1. Create charm storage pool (if necessary) + 1. Create storage pools 1. Deploy a Kubernetes charm ### Obtain a Kubernetes cluster -There are many ways you may obtain a Kubernetes cluster. Here is a list of +There are many ways to obtain a Kubernetes cluster. Here is a list of suggestions: - 1. Use the [kubernetes-core][kubernetes-core-charm] bundle, which gives a - minimal two-machine cluster available in the Charm Store. - 1. Use the [canonical-kubernetes][kubernetes-cdk-charm] bundle. This is the - Canonical Distribution of Kubernetes (CDK), which is a more sophisticated - version of what we used above. - 1. Use the [conjure-up][upstream-conjure-up] installer. See Ubuntu tutorial - [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] - for guidance. Although the tutorial specifically mentions the CDK bundle - you can choose the core bundle from the installer's interface. - 1. Use [MicroK8s][upstream-microk8s] where you get a local, fully compliant - Kubernetes deployment with dynamic persistent volume support. See tutorial - [Using Juju with microk8s][tutorial-microk8s]. - 1. Use a bundle made for the major cloud vendors. There are special - "integrator" charms that assist with such deployments. - [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. - 1. Use a public Kubernetes vendor such as - [Amazon EKS][upstream-eks-kubernetes], - [Azure AKS][upstream-aks-kubernetes], and - [Google GKE][upstream-gke-kubernetes]. + - Use the [kubernetes-core][kubernetes-core-charm] bundle, which gives a + minimal two-machine cluster available in the Charm Store. + - Use the [canonical-kubernetes][kubernetes-cdk-charm] bundle. This is the + Canonical Distribution of Kubernetes (CDK), which is a more sophisticated + version of what we used above. + - Use the [conjure-up][upstream-conjure-up] installer. See Ubuntu tutorial + [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] + for guidance. Although the tutorial specifically mentions the CDK bundle + you can choose the core bundle from the installer's interface. + - Use [MicroK8s][upstream-microk8s] where you get a local, fully compliant + Kubernetes deployment with dynamic persistent volume support. See tutorial + [Using Juju with microk8s][tutorial-microk8s]. + - Use a bundle made for the major cloud vendors. There are special + "integrator" charms that assist with such deployments. + [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. + - Use a public Kubernetes cloud vendor such as + [Amazon EKS][upstream-eks-kubernetes], + [Azure AKS][upstream-aks-kubernetes], and + [Google GKE][upstream-gke-kubernetes]. !!! Note: Kubernetes bundles do not work well on a LXD cloud at this time. Refer to @@ -122,11 +127,13 @@ juju add-model k8s-model k8s-cloud ``` This will cause a Kubernetes namespace in the cluster to be created that will -host all of the pods and other resources for that model. +host all of the pods and other resources for that model. The namespace is the +name of the Juju model. A Kubernetes Juju model also starts off with a storage +pool called 'kubernetes'. You can see this with the `storage-pools` command. !!! Note: - We've reused the model name of 'k8s-model' elsewhere on this page. Replace - it with your own model name. + We reuse the model name of 'k8s-model' elsewhere on this page to designate, + in general, a Kubernetes model. ### Create persistent storage @@ -243,6 +250,7 @@ kubectl -n k8s-model describe pvc [upstream-kubernetes-docs-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator +[charms-storage-k8s]: ./charms-storage-k8s.md [charms-storage-k8s-static-pv]: ./charms-storage-k8s.md#statically-provisioned-volumes [charms-storage-k8s-pool-creation]: ./charms-storage-k8s.md#storage-pool-creation [charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index f9b4a9b38..b53c3ef77 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -4,15 +4,15 @@ TODO: bug tracking: https://bugs.launchpad.net/juju/+bug/1804495 # Using Juju with MicroK8s *This is in connection to the topic of -[Using Kubernetes with Juju][clouds-k8s]. See that resource for background +[Using Kubernetes with Juju][clouds-k8s]. See that page for background information.* -Juju is compatible with the [microk8s][upstream-microk8s] project, which aims +Juju is compatible with the [MicroK8s][upstream-microk8s] project, which aims to provide "a full Kubernetes system in under 60 seconds". It is quite remarkable actually. It is composed of pure upstream binaries, runs all services natively (i.e. no virtual machines or containers), and is fully [CNCF certified][upstream-cncf]. This option is perfect for testing Kubernetes -on your laptop. Using it with Juju is icing on the cake! +on your personal workstation. Using it with Juju is icing on the cake! Since MicroK8s runs locally we'll be using a local LXD cloud to create a Juju controller. @@ -210,7 +210,7 @@ To remove all traces of MicroK8s and its configuration follow these steps: ```bash juju destroy-model -y --destroy-storage k8s-model -juju remove-cloud microk8s-cloud +juju remove-k8s microk8s-cloud microk8s.reset sudo snap remove microk8s ``` @@ -228,7 +228,7 @@ That's the end of this tutorial! ## Next steps -For more experience with a standalone (non-Juju) MicroK8s installation you can +To gain experience with a standalone (non-Juju) MicroK8s installation you can go through Ubuntu tutorial [Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. From b189df1eea0912421ac112a40d6aca155ff13074 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 27 Nov 2018 20:06:28 -0500 Subject: [PATCH 158/311] add zones constraint; minor improvments and corrections --- src/en/charms-constraints.md | 30 ++++++++++++---- src/en/charms-deploying-advanced.md | 56 +++++++++++++++++++++++------ src/en/charms-deploying.md | 8 +++++ src/en/reference-constraints.md | 12 +++++-- 4 files changed, 87 insertions(+), 19 deletions(-) diff --git a/src/en/charms-constraints.md b/src/en/charms-constraints.md index c974afce5..be769ea1f 100644 --- a/src/en/charms-constraints.md +++ b/src/en/charms-constraints.md @@ -6,19 +6,22 @@ TODO: Important: include default resources requested for non-constrained machin # Using constraints A *constraint* is a user-defined minimum hardware specification for a machine -that is spawned by Juju. There are a total of nine types of constraint, with +that is spawned by Juju. There are a total of ten types of constraint, with the most common ones being 'mem', 'cores', 'root-disk', and 'arch'. The definitive constraint resource is found on the [Reference: Juju constraints][reference-constraints] page. Several noteworthy constraint characteristics: - - Whenever a new machine is spawned (with commands `bootstrap`, `deploy`, - `add-unit`, or `add-machine`) a constraint can be specified. + - A constraint can be specified whenever a new machine is spawned with + commands `bootstrap`, `deploy`, or `add-machine`. - Some constraints are only supported by certain clouds. - - Changes to constraint defaults do not affect existing machines. + - When used with `deploy` the constraint becomes the application's default + constraint. - Multiple constraints are logically AND'd (i.e. the machine must satisfy all constraints). + - When used in conjunction with a placement directive (`--to` option), the + placement directive takes precedence. ## Clouds and constraints @@ -53,7 +56,7 @@ values will override corresponding instance type values. Constraints can be applied to various levels or scopes. Defaults can be set on some of them, and in the case of overlapping configurations a precedence is -adhered to. +adhered to. Changing a default does not affect existing machines. On a per-controller basis, the following constraint **scopes** exist: @@ -71,7 +74,7 @@ Among the scopes, **default** constraints can be set for each with the exception of the controller and single machines. The all-units scope has its default set dynamically. It is the possible -constraint used in the initial deployment of the corresponding application. +constraint used in the initial deployment of an application. The following **precedence** is observed (in order of priority): @@ -107,7 +110,7 @@ examples. to any future controllers provisioned for high availability. See [Controller high availability][controllers-ha]. -## Setting constraints for the controller and the default models +## Setting constraints for the initial 'controller' and 'default' models Constraints can be applied to **every** machine (controller and non-controller) in the 'controller' and 'default' models. This is done, again, during the @@ -203,6 +206,12 @@ of memory and 2 CPUs: juju deploy zookeeper --constraints "mem=5G cores=2" --to lxd ``` +To deploy two units of Redis across two AWS availability zones: + +```bash +juju deploy redis -n 2 --constraints zones=us-east-1a,us-east-1d +``` + An application's current constraints are displayed with the `get-constraints` command: @@ -265,6 +274,13 @@ For a LXD cloud, to create a machine limited to two CPUs: juju add-machine --constraints cores=2 ``` +To add eight Xenial machines such that they are evenly distributed among four +availability zones: + +```bash +juju add-machine -n 8 --series xenial --constraints zones=us-east-1a,us-east-1b,us-east-1c,us-east-1d +``` + diff --git a/src/en/charms-deploying-advanced.md b/src/en/charms-deploying-advanced.md index 662e7167e..cc8d7c01e 100644 --- a/src/en/charms-deploying-advanced.md +++ b/src/en/charms-deploying-advanced.md @@ -75,17 +75,20 @@ details. ## Deploying to specific machines -To deploy to specific machines the `--to` option is used. When this is done, -unless the machine was created via `add-machine`, a charm has already been -deployed to the machine. +To deploy to specific machines the `--to` option is used. It is supported by +commands `bootstrap`, `deploy`, and `add-unit`. -!!! Warning: - When multiple charms are deployed to the same machine there exists the - possibility of conflicting configuration files (on the machine's - filesystem). +The argument to the `--to` option is called a *placement directive*. -The `--to` option can be used with commands `bootstrap`, `deploy`, and -`add-unit`. +When this option is used, unless the machine was created via `add-machine`, a +charm has already been deployed to the machine. When multiple charms are +deployed to the same machine there exists the chance of conflicting +configuration files (on the machine's filesystem). + +!!! Note: + There is one type of placement directive that can also be used as a + constraint: availability zones. If used together, the placement directive + takes precedence. See [Using constraints][charms-constraints] for details. To apply this option towards an existing Juju machine, the machine ID is used. This is an integer that is shown in the output to `juju status` (or @@ -99,7 +102,7 @@ Machine State DNS Inst id Series AZ Message The above works well with `deploy` and `add-unit` as will be shown below. As for `bootstrap` the `--to` option is limited to either pointing to a MAAS node -or, starting in `v.2.5`, to a LXD cluster node. +or, starting in `v.2.5.0`, to a LXD cluster node. Assuming a MAAS cloud named 'maas-prod' exists and has a node called 'node2.maas': @@ -190,6 +193,39 @@ juju add-unit rabbitmq-server -n 2 --to node1.lxd,node2.lxd,node3.lxd The `add-unit` command is often associated with scaling out. See the [Scaling applications][charms-scaling] page for information on that topic. +## Deploying to specific availability zones + +To deploy to specific availability zones the `--constraints` option is used. It +is supported by commands `bootstrap`, `deploy`, and `add-machine`. + +The constraint type that is used to do this is 'zones'. This is not to be +confused with the 'zone' placement directive, which happens to take precedence +over the constraint. + +For instance, here we create two Trusty machines in a certain zone: + +```bash +juju add-machine -n 2 --series trusty --constraints zones=us-east-1a +``` + +We then deploy an application on two new machines in a different zone: + +```bash +juju deploy redis -n 2 --constraints zones=us-east-1c +``` + +Finally, in order to deploy units to the two empty machines in the initial zone +we first change the application constraint default (set implicitly with the +`deploy` command): + +```bash +juju set-constraints redis zones=us-east-1a +juju add-unit redis -n 2 +``` + +When multiple (comma separated) values are used, the constraint is interpreted +as being a range of zones where a machine must end up in. + ## Deploying to network spaces Using spaces, the operator is able to create a more restricted network topology diff --git a/src/en/charms-deploying.md b/src/en/charms-deploying.md index 5470d7f1d..e076cc9e2 100644 --- a/src/en/charms-deploying.md +++ b/src/en/charms-deploying.md @@ -163,6 +163,13 @@ You can specify which machine (or container) an application is to be deployed to. See [Deploying to specific machines][deploying-to-specific-machines] for full coverage of this topic. +## Deploying to specific availability zones + +It is possible to dictate what availability zone (or zones) a machine must be +installed in. See +[Deploying to specific availability zones][deploying-to-specific-zones] for +details. + ## Deploying to network spaces Using network spaces you can create a more restricted network topology for @@ -190,5 +197,6 @@ matter. [network-spaces]: ./network-spaces.md [deploying-multi-series-charms]: ./charms-deploying-advanced.md#multi--series-charms [deploying-to-specific-machines]: ./charms-deploying-advanced.md#deploying-to-specific-machines +[deploying-to-specific-zones]: ./charms-deploying-advanced.md#deploying-to-specific-availability-zones [deploying-to-network-spaces]: ./charms-deploying-advanced.md#deploying-to-network-spaces [#exposing-deployed-applications]: #exposing-deployed-applications diff --git a/src/en/reference-constraints.md b/src/en/reference-constraints.md index 25884ebb2..1460dfeb8 100644 --- a/src/en/reference-constraints.md +++ b/src/en/reference-constraints.md @@ -50,10 +50,10 @@ For in-depth coverage and examples see the denoting an attribute of the machine, or negative (prefixed with "^"), to denote something that the machine does not have. - **Note:** Currently only supported by the MAAS provider. - Example: tags=virtual,^dualnic + **Note:** Currently only supported by the MAAS provider. + - `spaces` A comma-delimited list of Juju network space names that a unit or machine needs access to. Space names can be positive, listing an attribute of the @@ -70,6 +70,14 @@ For in-depth coverage and examples see the - `virt-type` Virtualization type, such as 'kvm'. + - `zones` + A list of availability zones. Values vary by provider. Multiple values + present a range of zones that a machine must be created within. + + Example: zones=us-east-1a,us-east-1c + + **Note:** A zone can also be used as a placement directive (`--to` option). + ## Cloud differences Constraints cannot be applied towards a backing cloud in an agnostic way. That From e840348e0f7bc38ca558073ca4a72a8424e9e6d9 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 28 Nov 2018 18:57:28 -0500 Subject: [PATCH 159/311] add tutorial for static pv --- src/en/charms-storage-k8s.md | 13 +- src/en/clouds-k8s.md | 8 +- src/en/tutorial-k8s-static-pv.md | 302 +++++++++++++++++++++++++++++++ src/en/tutorial-microk8s.md | 12 +- 4 files changed, 325 insertions(+), 10 deletions(-) create mode 100644 src/en/tutorial-k8s-static-pv.md diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index de0cf86c7..d4de59ac6 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -48,8 +48,8 @@ In both cases, a Juju storage pool needs to be created by the Juju operator. The second type is needed when the storage system for your chosen backing cloud is not supported by Kubernetes. This situation therefore demands that volumes be set up prior to the creation of the storage pool. See -[Types of persistent volumes][upstream-kubernetes-volumes] for the list of -Kubernetes supported backends. +[Types of supported persistent volumes][upstream-kubernetes-supported-volume-types] +for the list of Kubernetes supported backends. Static volumes are mainly intended for testing/prototyping. @@ -69,9 +69,9 @@ The example YAML-formatted files `operator-storage.yaml` and `charm-storage-vol1.yaml` define volumes for operator storage and charm storage respectively that get created by the `kubectl` command. -The content of the volume definition files are given below. Typically multiple -charm storage volumes would be required. Note that operator storage needs a -minimum of 1024 MiB. +Example content of the volume definition files are given below. Typically +multiple charm storage volumes would be required. Note that operator storage +needs a minimum of 1024 MiB. ^# operator-storage.yaml @@ -256,7 +256,8 @@ provisioned volumes, respectively. [charms-storage]: ./charms-storage.md -[upstream-kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes +[upstream-kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes [upstream-kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ [#creating-storage-pools]: #creating-storage-pools [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 +[tutorial-microk8s]: ./tutorial-microk8s.md diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 1c2e2ac7f..eea10d742 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -4,8 +4,8 @@ TODO: Should eventually link to k8s-charm developer documentation Consider manually adding a cluster via `add-cloud` and `add-credential` Change from staging store to production store when available Link to Discourse posts on aws-integrator? - Write tutorial on building a cluster using GKE - Write tutorial on building a cluster using AWS + Write tutorial on building a cluster using GCE with gcp-integrator + Write tutorial on building a cluster using AWS with aws-integrator Example done with AWS since a LXD bundle needs each of its charms to specify profile edits according to https://is.gd/dqXGN2 # Using Kubernetes with Juju @@ -150,6 +150,9 @@ kubectl create -f charm-storage-vol1.yaml For assistance with the contents of these files see section [Statically provisioned volumes][charms-storage-k8s-static-pv]. +There is also a tutorial on setting up static persistent volumes here: +[Setting up static Kubernetes storage][tutorial-k8s-static-pv] + ### Create storage pools Create storage pools for operator storage and, if needed, charm storage. We @@ -256,6 +259,7 @@ kubectl -n k8s-model describe pvc [charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles [charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy [tutorial-microk8s]: ./tutorial-microk8s.md +[tutorial-k8s-static-pv]: ./tutorial-k8s-static-pv.md [kubernetes-deploying-on-lxd]: https://github.com/juju-solutions/bundle-canonical-kubernetes/wiki/Deploying-on-LXD [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md new file mode 100644 index 000000000..4c83a11f4 --- /dev/null +++ b/src/en/tutorial-k8s-static-pv.md @@ -0,0 +1,302 @@ +Title: Setting up static Kubernetes storage + +# Setting up static Kubernetes storage + +*This is in connection to the topic of +[Using Kubernetes with Juju][clouds-k8s]. See that page for background +information.* + +This short tutorial will show the steps required to create Kubernetes +persistent storage volumes for use with Juju. This is normally done when the +backing cloud you're using does not have a storage type that is supported +natively by Kubernetes. There is no reason, however, why you cannot use +statically provisioned volumes with any cloud. Here, we'll use AWS as our +backing cloud. Kubernetes does support AWS/EBS volumes (as shown +[here][upstream-kubernetes-supported-volume-types]) but it does require the use +of the [`aws-integrator`][charm-store-staging-aws-integrator] charm, which +we'll cover in a separate tutorial. + +The [Persistent storage and Kubernetes][charms-storage-k8s] page provides a +theoretical background on how Kubernetes storage works with Juju. + +## Pre-requisites + +The following requirements are assumed: + + - that you're using Ubuntu 18.04 LTS + - that Juju (stable snap channel) is installed. See the + [Installing Juju][reference-install] page. + - that a credential for the 'aws' cloud has been added to Juju. See + the [Credentials][credentials] page. + +## Preliminaries + +Let's begin creating a controller: + +```bash +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore aws aws-k8s +``` + +!!! Note: + We've used the staging Charm Store in these instructions as the standard + site does not yet support Kubernetes charms and bundles. + +## Installing Kubernetes + +For the purposes of this guide a complex Kubernetes cluster is not needed. +We've therefore chosen to use the 'kubernetes-core' bundle, which will give us +a minimalist cluster. Let's install it now: + +```bash +juju deploy kubernetes-core +``` + +After about ten minutes things should have settled down to arrive at a stable +output to the `status` command: + +```bash +juju status +``` + +Our example's output shows: + +```no-highlight +Model Controller Cloud/Region Version SLA Timestamp +default aws-k8s aws/us-east-1 2.5-beta2 unsupported 21:33:30Z + +App Version Status Scale Charm Store Rev OS Notes +easyrsa 3.0.1 active 1 easyrsa jujucharms 117 ubuntu +etcd 3.2.10 active 1 etcd jujucharms 209 ubuntu +flannel 0.10.0 active 2 flannel jujucharms 146 ubuntu +kubernetes-master 1.12.2 active 1 kubernetes-master jujucharms 219 ubuntu exposed +kubernetes-worker 1.12.2 active 1 kubernetes-worker jujucharms 239 ubuntu exposed + +Unit Workload Agent Machine Public address Ports Message +easyrsa/0* active idle 0/lxd/0 10.90.92.117 Certificate Authority connected. +etcd/0* active idle 0 54.158.28.106 2379/tcp Healthy with 1 known peer +kubernetes-master/0* active idle 0 54.158.28.106 6443/tcp Kubernetes master running. + flannel/0* active idle 54.158.28.106 Flannel subnet 10.1.19.1/24 +kubernetes-worker/0* active idle 1 35.174.241.18 80/tcp,443/tcp Kubernetes worker running. + flannel/1 active idle 35.174.241.18 Flannel subnet 10.1.5.1/24 + +Machine State DNS Inst id Series AZ Message +0 started 54.158.28.106 i-00ccf0eb4565c019d bionic us-east-1a running +0/lxd/0 started 10.90.92.117 juju-590f65-0-lxd-0 bionic us-east-1a Container started +1 started 35.174.241.18 i-0168d3ad2c1f7b27c bionic us-east-1b running +``` + +## Adding the cluster to Juju + +We'll now copy over the cluster's main configuration file and then use the +`add-k8s` command to add the cluster to Juju's list of known clouds. Here, we +arbitrarily call the new cloud 'k8s-cloud': + +```bash +mkdir ~/.kube +juju scp kubernetes-master/0:config ~/.kube/config +juju add-k8s k8s-cloud +``` + +The success of this operation can be confirmed by running `juju clouds`. + +## Adding a model + +When we add a Kubernetes cluster to Juju we effectively have two clouds being +managed by one controller. For us, they are named 'aws' and 'k8s-cloud'. So +when we want to create a model we'll need explicitly state which cloud to place +the new model in. We'll do this now by adding a model called 'k8s-model' to +cloud 'k8s-cloud': + +```bash +juju add-model k8s-model k8s-cloud +``` + +The output to `juju models` should now look very similar to: + +```no-highlight +Controller: aws-k8s + +Model Cloud/Region Status Machines Cores Access Last connection +controller aws/us-east-1 available 1 4 admin just now +default aws/us-east-1 available 3 8 admin 35 minutes ago +k8s-model* k8s-cloud available 0 - admin 14 seconds ago +``` + +## Static persistent volumes + +We've now reached the step where we can achieve the main goal of this tutorial. +We will now create persistent volumes, or PVs in Kubernetes parlance. Another +way of saying this is that we will set up statically provisioned storage. + +There are two types of storage: operator storage and charm storage (also called +unit storage). The bare minimum is one volume for operator storage. The +necessity of charm storage depends on the charms that will be deployed. Charm +storage is needed if the charm has storage requirements. The size and number of +those volumes are determined by those requirements and the nature of the charm +itself. + +The creation of volumes is a two-step process. First set up definition files +for each PV, and second, create the actual PVs using `kubectl`, the Kubernetes +configuration management tool. We'll look at these two steps now. + +### Defining persistent volumes + +YAML-formatted + +^# operator-storage.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: op1 + spec: + capacity: + storage: 1032Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: k8s-model-juju-operator-storage + hostPath: + path: "/mnt/data/op1" + +^# charm-storage-vol1.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: vol1 + spec: + capacity: + storage: 100Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: k8s-model-juju-unit-storage + hostPath: + path: "/mnt/data/vol1" + +^# charm-storage-vol2.yaml + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: vol2 + spec: + capacity: + storage: 100Mi + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storageClassName: k8s-model-juju-unit-storage + hostPath: + path: "/mnt/data/vol2" + +!!! Important: + The storage class name for a statically provisioned volume must be prefixed + with the name of the intended model. In the examples above, the model name + is 'k8s-model'. The remainder of the name, for both operator and charm + storage, are fixed. This is explained again further on. + + +### Creating persistent volumes + +The actual creation of the volumes is very easy. Simply refer the `kubectl` +command to the files. We begin by installing the tool if it's not yet present: + +```bash +sudo snap install --classic kubectl +kubectl create -f operator-storage.yaml +kubectl create -f charm-storage-vol1.yaml +kubectl create -f charm-storage-vol2.yaml +``` + +This tool is communicating directly with the cluster and can do so based on the +configuration file that was copied over earlier. + +## Creating Juju storage pools + +Whether or not storage volumes are provisioned statically or dynamically Juju +storage pools must be created. And this must be done for both operator storage +and charm storage. + +Below we have Juju create two storage pools, one for +operator storage and one for charm storage: + +```bash +``` + +## Deploying a Kubernetes charm + +We can now deploy a Kubernetes charm. For example, here we deploy a charm by +requesting the use of the 'mariadb-pv' charm storage pool we just set up: + +```bash +juju deploy cs:~wallyworld/mariadb-k8s --storage database=mariadb-pv,10M +``` + +The output to `juju status` should soon look like the following: + +```no-highlight +``` + +In contrast to standard Juju behaviour, there are no machines listed here. +Let's see what has happened within the cluster: + +```bash +microk8s.kubectl get all --all-namespaces +``` + +New sample output: + +```no-highlight +``` + +You can easily identify the changes, as compared to the initial output, by +scanning the left hand side for the model name we chose: 'k8s-model', which +ends up being the Kubernetes "namespace". + +## Removing configuration and software + +To remove all traces of MicroK8s and its configuration follow these steps: + +```bash +juju destroy-model -y --destroy-storage k8s-model +juju remove-k8s microk8s-cloud +microk8s.reset +sudo snap remove microk8s +``` + +This leaves us with LXD and Juju installed as well as a LXD controller. To +remove even those things proceed as follows: + +```bash +juju destroy-controller -y lxd +sudo snap remove lxd +sudo snap remove juju +``` + +That's the end of this tutorial! + +## Next steps + +To explore using Juju with the MicroK8s project consider the following +tutorial: + +[Using Juju with MicroK8s][tutorial-microk8s]. + +To gain experience with a standalone (non-Juju) MicroK8s installation you can +go through this Ubuntu tutorial: + +[Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. + + + + +[clouds-k8s]: ./clouds-k8s.md +[upstream-cncf]: https://www.cncf.io/certification/software-conformance/ +[charms-storage-k8s]: ./charms-storage-k8s.md +[ubuntu-tutorial_kubernetes-microk8s]: https://tutorials.ubuntu.com/tutorial/install-a-local-kubernetes-with-microk8s +[charm-store-staging-aws-integrator]: https://staging.jujucharms.com/u/johnsca/aws-integrator +[upstream-kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes +[credentials]: ./credentials.md +[install]: ./reference-install.md diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index b53c3ef77..fe5ef9ec3 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -135,7 +135,7 @@ in-depth information on how Kubernetes storage works with Juju. ## Deploying a Kubernetes charm -We can deploy a Kubernetes charm. For example, here we deploy a charm by +We can now deploy a Kubernetes charm. For example, here we deploy a charm by requesting the use of the 'mariadb-pv' charm storage pool we just set up: ```bash @@ -229,9 +229,16 @@ That's the end of this tutorial! ## Next steps To gain experience with a standalone (non-Juju) MicroK8s installation you can -go through Ubuntu tutorial +go through this Ubuntu tutorial: + [Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. +As alluded to, some backing clouds may require you to create persistent +volumes, on top of creating the storage pools. The following tutorial will go +over this in detail: + +[Setting up static Kubernetes storage][tutorial-k8s-static-pv] + @@ -241,3 +248,4 @@ go through Ubuntu tutorial [charms-storage-k8s]: ./charms-storage-k8s.md [upstream-kubectl-viewing]: https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-finding-resources [ubuntu-tutorial_kubernetes-microk8s]: https://tutorials.ubuntu.com/tutorial/install-a-local-kubernetes-with-microk8s +[tutorial-k8s-static-pv]: ./tutorial-k8s-static-pv.md From 1e689378c41c977851184758a2a4583e65152f26 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 29 Nov 2018 13:05:24 -0500 Subject: [PATCH 160/311] ongoing --- src/en/charms-storage-k8s.md | 30 ++++++----- src/en/clouds-k8s.md | 61 ++++++++++++---------- src/en/tutorial-k8s-static-pv.md | 87 +++++++++++++++++++++++++------- 3 files changed, 119 insertions(+), 59 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index d4de59ac6..1e1b93df5 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -48,16 +48,20 @@ In both cases, a Juju storage pool needs to be created by the Juju operator. The second type is needed when the storage system for your chosen backing cloud is not supported by Kubernetes. This situation therefore demands that volumes be set up prior to the creation of the storage pool. See -[Types of supported persistent volumes][upstream-kubernetes-supported-volume-types] -for the list of Kubernetes supported backends. +[Types of volumes][kubernetes-supported-volume-types] for the list of +Kubernetes supported backends. -Static volumes are mainly intended for testing/prototyping. +!!! Important: + Static volumes are mainly intended for testing/prototyping. They need the + Kubernetes [`hostPath`][kubernetes-hostpath] plugin, which only works with a cluster consisting of + a single worker node. +Juju-managed storage is in contrast to external storageA #### Statically provisioned volumes You set up static volumes via YAML definition files. The -[Kubernetes storage classes][upstream-kubernetes-classes] page offers details. -Here is a example procedure: +[Kubernetes storage classes][kubernetes-classes] page offers details. Here is +a example procedure: ```bash sudo snap install --classic kubectl @@ -192,11 +196,11 @@ juju create-storage-pool operator-storage kubernetes \ ``` !!! Important: - When creating a pool with the 'no-provisioner' type, Juju will prefix the - current model's name to the stated storage class name. In the above - example, assuming a model name of 'k8s-model', the final storage class name - associated with the pool becomes 'k8s-model-juju-operator-storage'. It is - this name that you must use when defining a static volume (YAML file). + When creating a pool, Juju will prefix the current model's name to the + stated storage class name. In the above example, assuming a model name of + 'k8s-model', the final storage class name associated with the pool becomes + 'k8s-model-juju-operator-storage'. It is this name that you must use when + defining a static volume (YAML file). #### Creating charm storage pools @@ -256,8 +260,10 @@ provisioned volumes, respectively. [charms-storage]: ./charms-storage.md -[upstream-kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes -[upstream-kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ +[kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/volumes/#types-of-volumes +[kubernetes-hostpath]: https://kubernetes.io/docs/concepts/storage/volumes/#hostpath +[kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ [#creating-storage-pools]: #creating-storage-pools [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 [tutorial-microk8s]: ./tutorial-microk8s.md +[#external-storage-and-storage-precedence-rules]: #external-storage-and-storage-precedence-rules diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index eea10d742..4d235fb0c 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -3,7 +3,6 @@ TODO: Should eventually link to k8s-charm developer documentation Add architectural overview/diagram Consider manually adding a cluster via `add-cloud` and `add-credential` Change from staging store to production store when available - Link to Discourse posts on aws-integrator? Write tutorial on building a cluster using GCE with gcp-integrator Write tutorial on building a cluster using AWS with aws-integrator Example done with AWS since a LXD bundle needs each of its charms to specify profile edits according to https://is.gd/dqXGN2 @@ -11,11 +10,12 @@ TODO: Should eventually link to k8s-charm developer documentation # Using Kubernetes with Juju Kubernetes ("k8s") provides a flexible architecture for managing containerised -applications at scale (see the -[Kubernetes documentation][upstream-kubernetes-docs] for more information). It -most commonly employs Docker as its container technology. +applications at scale. See the +[Kubernetes documentation][upstream-kubernetes-docs] for more information. -These instructions refer to page +??????? JUJU blah blah blah ???????? + +This document refers to page [Persistent storage and Kubernetes][charms-storage-k8s] in a few places. You may want to familiarise yourself with it now. @@ -23,7 +23,7 @@ may want to familiarise yourself with it now. The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and `scale-application`. All other concepts and commands are applied in the -traditional Juju manner. +traditional manner. The `add-k8s` command is used to add the Kubernetes cluster to Juju's list of known clouds and import its credentials. The cluster configuration file will @@ -43,7 +43,7 @@ The `remove-k8s` command is used to remove a Kubernetes cluster from Juju's list of known clouds. The `scale-application` command is used to scale a Kubernetes cluster. The -`add-unit` and `remove-unit` commands cannot be applied to a Kubernetes model. +`add-unit` and `remove-unit` commands do not apply to a Kubernetes model. ## Using Kubernetes with Juju @@ -67,17 +67,21 @@ There are many ways to obtain a Kubernetes cluster. Here is a list of suggestions: - Use the [kubernetes-core][kubernetes-core-charm] bundle, which gives a - minimal two-machine cluster available in the Charm Store. + minimal two-machine cluster available in the Charm Store. The tutorial + [Setting up static Kubernetes storage][tutorial-k8s-static-pv] uses this + bundle. - Use the [canonical-kubernetes][kubernetes-cdk-charm] bundle. This is the Canonical Distribution of Kubernetes (CDK), which is a more sophisticated - version of what we used above. - - Use the [conjure-up][upstream-conjure-up] installer. See Ubuntu tutorial - [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] - for guidance. Although the tutorial specifically mentions the CDK bundle - you can choose the core bundle from the installer's interface. - - Use [MicroK8s][upstream-microk8s] where you get a local, fully compliant - Kubernetes deployment with dynamic persistent volume support. See tutorial - [Using Juju with microk8s][tutorial-microk8s]. + version of 'kubernetes-core'. + - Use the [conjure-up][upstream-conjure-up] installer. See the following + resources for guidance: + - The Ubuntu tutorial: + [Install Kubernetes with conjure-up][ubuntu-tutorial_install-kubernetes-with-conjure-up] + - The upstream getting started guide: + [Spell Walkthrough][upstream-conjure-up-guide] + - Use [MicroK8s][upstream-microk8s]. This gives you get a local, fully + compliant Kubernetes deployment with dynamic persistent volume support. See + tutorial [Using Juju with microk8s][tutorial-microk8s]. - Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. @@ -96,8 +100,8 @@ We will need some information about the cluster in order to add it to Juju. This is found within the main Kubernetes configuration file. !!! Note: - If `conjure-up` was used to install the cluster then the rest of this - section can be skipped; this install method adds the cluster for you. + The `conjure-up` installer adds the cluster for you. The rest of this + section can be skipped if that's what you used. The configuration file can be copied over from the Kubernetes master node (and saved as `~/.kube/config`). Here is one way you can do this if Juju was used to @@ -108,15 +112,15 @@ mkdir ~/.kube juju scp kubernetes-master/0:config ~/.kube/config ``` -We can now take advantage of the `add-k8s` command as it internally parses the -copied configuration file from the specified path. This allows us to quickly -add the cluster-cloud, which we have arbitrarily called 'k8s-cloud': +We can now take advantage of the `add-k8s` command as it will parse the +configuration file if copied to the above path. This allows us to quickly add +the cluster, which we have arbitrarily called 'k8s-cloud': ```bash juju add-k8s k8s-cloud ``` -Now confirm the successful addition of the cloud with the `clouds` command. +Confirm the successful addition of the cloud with the `clouds` command. ### Add a model @@ -133,7 +137,7 @@ pool called 'kubernetes'. You can see this with the `storage-pools` command. !!! Note: We reuse the model name of 'k8s-model' elsewhere on this page to designate, - in general, a Kubernetes model. + in general, a Kubernetes Juju model. ### Create persistent storage @@ -151,7 +155,7 @@ For assistance with the contents of these files see section [Statically provisioned volumes][charms-storage-k8s-static-pv]. There is also a tutorial on setting up static persistent volumes here: -[Setting up static Kubernetes storage][tutorial-k8s-static-pv] +[Setting up static Kubernetes storage][tutorial-k8s-static-pv]. ### Create storage pools @@ -248,10 +252,6 @@ kubectl -n k8s-model describe pvc [kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [kubernetes-cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ -[upstream-kubernetes-docs]: https://kubernetes.io/docs -[upstream-kubernetes-docs-service]: https://kubernetes.io/docs/concepts/services-networking/service/ -[upstream-kubernetes-docs-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ -[upstream-conjure-up]: https://conjure-up.io/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator [charms-storage-k8s]: ./charms-storage-k8s.md [charms-storage-k8s-static-pv]: ./charms-storage-k8s.md#statically-provisioned-volumes @@ -262,7 +262,12 @@ kubectl -n k8s-model describe pvc [tutorial-k8s-static-pv]: ./tutorial-k8s-static-pv.md [kubernetes-deploying-on-lxd]: https://github.com/juju-solutions/bundle-canonical-kubernetes/wiki/Deploying-on-LXD +[upstream-kubernetes-docs]: https://kubernetes.io/docs +[upstream-kubernetes-docs-service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[upstream-kubernetes-docs-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [upstream-eks-kubernetes]: https://aws.amazon.com/eks/ [upstream-aks-kubernetes]: https://azure.microsoft.com/en-us/services/kubernetes-service/ [upstream-gke-kubernetes]: https://cloud.google.com/kubernetes-engine/ [upstream-microk8s]: https://microk8s.io +[upstream-conjure-up]: https://conjure-up.io/ +[upstream-conjure-up-guide]: https://docs.conjure-up.io/stable/en/walkthrough diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md index 4c83a11f4..24b55c31a 100644 --- a/src/en/tutorial-k8s-static-pv.md +++ b/src/en/tutorial-k8s-static-pv.md @@ -12,13 +12,19 @@ backing cloud you're using does not have a storage type that is supported natively by Kubernetes. There is no reason, however, why you cannot use statically provisioned volumes with any cloud. Here, we'll use AWS as our backing cloud. Kubernetes does support AWS/EBS volumes (as shown -[here][upstream-kubernetes-supported-volume-types]) but it does require the use -of the [`aws-integrator`][charm-store-staging-aws-integrator] charm, which -we'll cover in a separate tutorial. +[here][kubernetes-supported-volume-types]; see 'AWSElasticBlockStore') but it +does require the use of the +[`aws-integrator`][charm-store-staging-aws-integrator] charm, which we'll cover +in a separate tutorial. The [Persistent storage and Kubernetes][charms-storage-k8s] page provides a theoretical background on how Kubernetes storage works with Juju. +Note that static volumes are dependent upon the Kubernetes +[`hostPath`][kubernetes-hostpath] volume type. This restricts us to a single +worker node cluster. The 'kubernetes-core' bundle provides this and that's +we'll be using here. + ## Pre-requisites The following requirements are assumed: @@ -43,9 +49,8 @@ juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charms ## Installing Kubernetes -For the purposes of this guide a complex Kubernetes cluster is not needed. -We've therefore chosen to use the 'kubernetes-core' bundle, which will give us -a minimalist cluster. Let's install it now: +Deploy Kubernetes using the 'kubernetes-core' bundle, which will give us +a minimalist cluster: ```bash juju deploy kubernetes-core @@ -58,7 +63,7 @@ output to the `status` command: juju status ``` -Our example's output shows: +Our example's output: ```no-highlight Model Controller Cloud/Region Version SLA Timestamp @@ -124,7 +129,6 @@ k8s-model* k8s-cloud available 0 - admin 14 seconds ago ## Static persistent volumes -We've now reached the step where we can achieve the main goal of this tutorial. We will now create persistent volumes, or PVs in Kubernetes parlance. Another way of saying this is that we will set up statically provisioned storage. @@ -191,12 +195,12 @@ YAML-formatted hostPath: path: "/mnt/data/vol2" + !!! Important: The storage class name for a statically provisioned volume must be prefixed with the name of the intended model. In the examples above, the model name is 'k8s-model'. The remainder of the name, for both operator and charm - storage, are fixed. This is explained again further on. - + storage, is fixed. ### Creating persistent volumes @@ -210,21 +214,64 @@ kubectl create -f charm-storage-vol1.yaml kubectl create -f charm-storage-vol2.yaml ``` -This tool is communicating directly with the cluster and can do so based on the -configuration file that was copied over earlier. +This tool is communicating directly with the cluster. It can do so by virtue of +the existence of the cluster configuration file (`~/.kube/config`). ## Creating Juju storage pools Whether or not storage volumes are provisioned statically or dynamically Juju -storage pools must be created. And this must be done for both operator storage -and charm storage. +storage pools must be created. This must be done for both operator storage +and charm storage on a per-model basis. The command to use is +`create-storage-pool`. + +The number of storage pools is dependent on the storage classes referenced in +the PV definition files. The simplest arrangement is to have a single storage +pool for each storage type and this is the approach our definition files above +have taken. The two storage classes are 'k8s-model-juju-operator-storage' and +'k8s-model-juju-unit-storage' . + +Naturally, then, during the creation process of a storage pool the storage +class is referenced. However, Juju will automatically prepend the name of the +current model (or that of the model specified via `-m`) to the referenced +storage class name. Omit, therefore, the model name portion of the storage +class when creating the pool. -Below we have Juju create two storage pools, one for -operator storage and one for charm storage: +The storage pool name for operator storage *must* be called 'operator-storage' +while the pool name for charm storage is arbitrary. Here, we'll call it +'k8s-pool'. It is the charm storage pool name that will be called during the +deployment of a charm. + +For static volumes, the Kubernetes "storage provisioner" is called +'kubernetes.io/no-provisioner'. + +Finally, the "storage provider" is called 'kubernetes'. This provider became +available once the Kubernetes model was added. + +Putting this all together, then, our two storage pools are created in this way: ```bash +juju create-storage-pool operator-storage kubernetes \ + storage-class=juju-operator-storage \ + storage-provisioner=kubernetes.io/no-provisioner +juju create-storage-pool k8s-pool kubernetes \ + storage-class=juju-unit-storage \ + storage-provisioner=kubernetes.io/no-provisioner ``` +Perform a verification by listing all current storage pools with the +`storage-pools` command: + +```bash +juju storage-pools +``` + +Our example's output: + +```no-highlight +``` + +Almost there! + ## Deploying a Kubernetes charm We can now deploy a Kubernetes charm. For example, here we deploy a charm by @@ -287,7 +334,7 @@ tutorial: To gain experience with a standalone (non-Juju) MicroK8s installation you can go through this Ubuntu tutorial: -[Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. +[Install a local Kubernetes with MicroK8s][ubuntu-tutorial-kubernetes-microk8s]. @@ -295,8 +342,10 @@ go through this Ubuntu tutorial: [clouds-k8s]: ./clouds-k8s.md [upstream-cncf]: https://www.cncf.io/certification/software-conformance/ [charms-storage-k8s]: ./charms-storage-k8s.md -[ubuntu-tutorial_kubernetes-microk8s]: https://tutorials.ubuntu.com/tutorial/install-a-local-kubernetes-with-microk8s +[ubuntu-tutorial-kubernetes-microk8s]: https://tutorials.ubuntu.com/tutorial/install-a-local-kubernetes-with-microk8s [charm-store-staging-aws-integrator]: https://staging.jujucharms.com/u/johnsca/aws-integrator -[upstream-kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes +[kubernetes-supported-volume-types]: https://kubernetes.io/docs/concepts/storage/volumes/#types-of-volumes [credentials]: ./credentials.md [install]: ./reference-install.md +[tutorial-microk8s]: ./tutorial-microk8s.md +[kubernetes-hostpath]: https://kubernetes.io/docs/concepts/storage/volumes/#hostpath From 16ce258f249d3e26a4807a4e6c86b53a3488df5f Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 29 Nov 2018 15:58:26 -0500 Subject: [PATCH 161/311] more and more stuff --- src/en/charms-storage-k8s.md | 70 ++++++++--------- src/en/clouds-k8s.md | 9 ++- src/en/tutorial-k8s-static-pv.md | 126 +++++++++++++++++++++++++------ 3 files changed, 146 insertions(+), 59 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 1e1b93df5..30c120e0a 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -1,7 +1,5 @@ Title: Persistent storage and Kubernetes -TODO: Add how to create external storage - Write a tutorial or two on using storage - How to remove a static volume? +TODO: How to remove a static volume? # Persistent storage and Kubernetes @@ -37,7 +35,7 @@ Juju-managed storage can be provisioned either dynamically or statically. The topic of storage is covered in a non-Kubernetes context on the [Using Juju Storage][charms-storage] page. -### Juju-managed storage +## Juju-managed storage As mentioned, there are two types of persistent storage that Juju can manage: @@ -47,21 +45,33 @@ As mentioned, there are two types of persistent storage that Juju can manage: In both cases, a Juju storage pool needs to be created by the Juju operator. The second type is needed when the storage system for your chosen backing cloud is not supported by Kubernetes. This situation therefore demands that volumes -be set up prior to the creation of the storage pool. See -[Types of volumes][kubernetes-supported-volume-types] for the list of -Kubernetes supported backends. +be set up prior to the creation of the storage pool. + +See [Types of volumes][kubernetes-supported-volume-types] for the list of +Kubernetes supported storage backends. This will inform you whether your +backing cloud can use dynamically provisioned volumes. As of time of writing, +the list of Juju-supported clouds that also have dynamic volume support are: + + - Amazon AWS + - Google GCE + - Microsoft Azure + - OpenStack + - VMware vSphere !!! Important: Static volumes are mainly intended for testing/prototyping. They need the - Kubernetes [`hostPath`][kubernetes-hostpath] plugin, which only works with a cluster consisting of - a single worker node. + Kubernetes [`hostPath`][kubernetes-hostpath] plugin, which only works with + a cluster consisting of a single worker node. -Juju-managed storage is in contrast to external storageA -#### Statically provisioned volumes +Juju-managed storage is in contrast to +[external storage][#external-storage-and-storage-precedence-rules], covered +later on. + +### Statically provisioned volumes You set up static volumes via YAML definition files. The -[Kubernetes storage classes][kubernetes-classes] page offers details. Here is -a example procedure: +[Kubernetes storage classes][kubernetes-classes] page offers details as to the +structure of the file. Here is the generic procedure: ```bash sudo snap install --classic kubectl @@ -109,20 +119,17 @@ needs a minimum of 1024 MiB. hostPath: path: "/mnt/data/vol1" +Once a static volume is used, it is never re-used, even if the unit/pod is +terminated and the volume is released. Just as static volumes are manually +created, they must also be manually removed. + !!! Important: The storage class name for a statically provisioned volume must be prefixed with the name of the intended model. In the examples above, the model name is 'k8s-model'. The remainder of the name, for both operator and charm storage, are fixed. This is explained again further on. -We'll show how to create Juju storage pools using our newly-created volumes in -the next section. - -Once a static volume is used, it is never re-used, even if the unit/pod is -terminated and the volume is released. Just as static volumes are manually -created, they must also be manually removed. - -### Storage pool creation +## Storage pool creation Juju storage pools are created for both operator storage and charm storage using the `create-storage-pool` command. Both are done by mapping to either a @@ -139,12 +146,6 @@ the `deploy` command. It is also this command that triggers the actual creation of the Kubernetes storage class when that storage class is referred to for the first time. - - The pool name for operator storage *must* be called 'operator-storage' while a pool name for charm storage is arbitrary. @@ -154,7 +155,7 @@ called 'juju-unit-storage'. The standard `storage-pools` command is used to list Juju storage pools. -#### Creating operator storage pools +### Creating operator storage pools The below examples show how to create operator storage pools for various scenarios. @@ -168,7 +169,7 @@ juju create-storage-pool operator-storage kubernetes \ parameters.type=gp2 ``` -For GKE using Persistent Disk (dynamically provisioned): +For GCE using Persistent Disk (dynamically provisioned): ```bash juju create-storage-pool operator-storage kubernetes \ @@ -184,7 +185,7 @@ juju create-storage-pool operator-storage kubernetes \ storage-class=microk8s-hostpath ``` -For microk8s, a special storage class name of 'microk8s-hostpath' is always +For MicroK8s, a special storage class name of 'microk8s-hostpath' is always used. For LXD (statically provisioned): @@ -202,7 +203,7 @@ juju create-storage-pool operator-storage kubernetes \ 'k8s-model-juju-operator-storage'. It is this name that you must use when defining a static volume (YAML file). -#### Creating charm storage pools +### Creating charm storage pools Creating a charm storage pool is done very similarly to creating an operator storage pool. The below example creates a pool arbitrarily called 'k8s-pool' @@ -226,7 +227,7 @@ juju create-storage-pool k8s-pool kubernetes \ storage-class=microk8s-hostpath ``` -### External storage and storage precedence rules +## External storage and storage precedence rules Although the recommended approach is to use Juju-managed storage, Juju does support externally created storage for both operator storage and charm storage. @@ -252,9 +253,8 @@ For charm storage the rules are similar: - `default` 1. a storage class with label `storageclass.kubernetes.io/is-default-class` -Notice that for both operator and charm storage, the first two rules are -compatible with Juju-managed statically provisioned volumes and dynamically -provisioned volumes, respectively. +Notice that for both operator and charm storage, the first rule is compatible +with Juju-managed statically provisioned volumes. diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 4d235fb0c..c6418b29f 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -13,7 +13,10 @@ Kubernetes ("k8s") provides a flexible architecture for managing containerised applications at scale. See the [Kubernetes documentation][upstream-kubernetes-docs] for more information. -??????? JUJU blah blah blah ???????? +Juju has the ability to add a Kubernetes cluster to its known list of clouds +and then treat it like it does any other cloud. There are some exceptions to +this and these are covered in the next section. In addition, +Kubernetes-specific charms are needed. This document refers to page [Persistent storage and Kubernetes][charms-storage-k8s] in a few places. You @@ -21,7 +24,7 @@ may want to familiarise yourself with it now. ## Juju Kubernetes-specific workflow -The only k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and +The k8s-specific Juju commands are `add-k8s`, `remove-k8s`, and `scale-application`. All other concepts and commands are applied in the traditional manner. @@ -32,7 +35,7 @@ combination of `add-cloud` and `add-credential` unnecessary. User credentials can still be added by way of the `add-credential` or `autoload-credentials` commands. Also, at any time, the k8s CLI can be used to -add a new user to the k8s cluster. +add a new user to the cluster. The `add-k8s` command can be used repeatedly to set up different clusters as long as the contents of the configuration file has been changed accordingly. diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md index 24b55c31a..62dacae2a 100644 --- a/src/en/tutorial-k8s-static-pv.md +++ b/src/en/tutorial-k8s-static-pv.md @@ -27,7 +27,7 @@ we'll be using here. ## Pre-requisites -The following requirements are assumed: +The following criteria are assumed: - that you're using Ubuntu 18.04 LTS - that Juju (stable snap channel) is installed. See the @@ -37,7 +37,7 @@ The following requirements are assumed: ## Preliminaries -Let's begin creating a controller: +Let's begin by creating a controller: ```bash juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore aws aws-k8s @@ -45,7 +45,7 @@ juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charms !!! Note: We've used the staging Charm Store in these instructions as the standard - site does not yet support Kubernetes charms and bundles. + site does not yet support Kubernetes charms. ## Installing Kubernetes @@ -127,6 +127,15 @@ default aws/us-east-1 available 3 8 admin 35 minutes ago k8s-model* k8s-cloud available 0 - admin 14 seconds ago ``` +Adding a model for a Kubernetes cloud unlocks the 'kubernetes' storage +provider, which we'll refer to later. The output to `juju storage-pools` should +be: + +```no-highlight +Name Provider Attrs +Kubernetes kubernetes +``` + ## Static persistent volumes We will now create persistent volumes, or PVs in Kubernetes parlance. Another @@ -145,7 +154,9 @@ configuration management tool. We'll look at these two steps now. ### Defining persistent volumes -YAML-formatted +In this tutorial we'll be creating one operator storage volume and two charm +storage volumes. The three corresponding files are below. Click on their names +to reveal their contents. ^# operator-storage.yaml @@ -195,11 +206,12 @@ YAML-formatted hostPath: path: "/mnt/data/vol2" +Note that operator storage needs a minimum of 1024 MiB. !!! Important: The storage class name for a statically provisioned volume must be prefixed - with the name of the intended model. In the examples above, the model name - is 'k8s-model'. The remainder of the name, for both operator and charm + with the name of the intended model. In the files above, the model name is + 'k8s-model'. The remainder of the name, for both operator and charm storage, is fixed. ### Creating persistent volumes @@ -217,6 +229,24 @@ kubectl create -f charm-storage-vol2.yaml This tool is communicating directly with the cluster. It can do so by virtue of the existence of the cluster configuration file (`~/.kube/config`). +We can also use this tool to take a look at our new PVs: + +```bash +kubectl -n k8s-model get sc,pv,pvc +``` + +Our example's output: + +```no-highlight +NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE +persistentvolume/op1 1032Mi RWO Retain Available k8s-model-juju-operator-storage 7m21s +persistentvolume/vol1 100Mi RWO Retain Available k8s-model-juju-unit-storage 7m16s +Persistentvolume/vol2 100Mi RWO Retain Available k8s-model-juju-unit-storage 7m12s +``` + +Notice how our model name of 'k8s-model' can be passed to `kubectl`. When the +Juju model was added a Kubernetes "namespace" was set up with the same name. + ## Creating Juju storage pools Whether or not storage volumes are provisioned statically or dynamically Juju @@ -268,6 +298,10 @@ juju storage-pools Our example's output: ```no-highlight +Name Provider Attrs +k8s-pool kubernetes storage-class=juju-unit-storage storage-provisioner=kubernetes.io/no-provisioner +kubernetes kubernetes +operator-storage kubernetes storage-class=juju-operator-storage storage-provisioner=kubernetes.io/no-provisioner ``` Almost there! @@ -275,51 +309,101 @@ Almost there! ## Deploying a Kubernetes charm We can now deploy a Kubernetes charm. For example, here we deploy a charm by -requesting the use of the 'mariadb-pv' charm storage pool we just set up: +requesting the use of the 'k8s-pool' charm storage pool we just set up: ```bash -juju deploy cs:~wallyworld/mariadb-k8s --storage database=mariadb-pv,10M +juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M ``` The output to `juju status` should soon look like the following: ```no-highlight +Model Controller Cloud/Region Version SLA Timestamp +k8s-model aws-k8s k8s-cloud 2.5-beta2 unsupported 20:42:28Z + +App Version Status Scale Charm Store Rev OS Address Notes +mariadb-k8s active 1 mariadb-k8s jujucharms 13 kubernetes 10.152.183.87 + +Unit Workload Agent Address Ports Message +mariadb-k8s/0* active idle 10.1.69.14 3306/TCP ``` In contrast to standard Juju behaviour, there are no machines listed here. -Let's see what has happened within the cluster: ```bash -microk8s.kubectl get all --all-namespaces +juju storage --filesystem +``` + +```no-highlight +Unit Storage id Id Provider id Mountpoint Size State Message +mariadb-k8s/0 database/0 0 juju-database-0-juju-mariadb-k8s-0 /var/lib/mysql 38MiB attached +``` + +```bash +juju storage --volume +``` + +```no-highlight +Unit Storage id Volume id Provider Id Size State Message +mariadb-k8s/0 database/0 0 vol1 409MiB attached +``` + +## Post-deploy cluster inspection + +Let's see what has happened within the cluster by interrogating it again: + +```bash +kubectl -n k8s-model get sc,pv,pvc ``` New sample output: ```no-highlight +NAME PROVISIONER AGE +storageclass.storage.k8s.io/k8s-model-juju-operator-storage kubernetes.io/no-provisioner 3m2s +storageclass.storage.k8s.io/k8s-model-juju-unit-storage kubernetes.io/no-provisioner 2m30s + +NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE +persistentvolume/op1 1032Mi RWO Retain Bound k8s-model/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 k8s-model-juju-operator-storage 7m5s +persistentvolume/vol1 100Mi RWO Retain Bound k8s-model/juju-database-0-juju-mariadb-k8s-0 k8s-model-juju-unit-storage 6m54s +persistentvolume/vol2 100Mi RWO Retain Available k8s-model-juju-unit-storage 6m51s + +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +persistentvolumeclaim/juju-database-0-juju-mariadb-k8s-0 Bound vol1 100Mi RWO k8s-model-juju-unit-storage 2m30s +persistentvolumeclaim/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 Bound op1 1032Mi RWO k8s-model-juju-operator-storage 3m2s ``` -You can easily identify the changes, as compared to the initial output, by -scanning the left hand side for the model name we chose: 'k8s-model', which -ends up being the Kubernetes "namespace". +Awesome. + +At the top we see that our two storage classes have been created and that +they're both associated with the 'no-provisioner' provisioner. + +In the middle section it is clear that two of our volumes are being used +('Bound') and that one is available. + +In the lower part we're told what has "claimed" the two used volumes. Each of +these claims have requested the use of the appropriate storage classes. ## Removing configuration and software -To remove all traces of MicroK8s and its configuration follow these steps: +To remove all traces of Kubernetes and its configuration follow these steps: ```bash juju destroy-model -y --destroy-storage k8s-model -juju remove-k8s microk8s-cloud -microk8s.reset -sudo snap remove microk8s +juju remove-k8s k8s-cloud +rm -rf ~/.kube +rm ~/operator-storage.yaml +rm ~/charm-storage-vol1.yaml +rm ~/charm-storage-vol2.yaml ``` -This leaves us with LXD and Juju installed as well as a LXD controller. To -remove even those things proceed as follows: +This leaves us with Juju and `kubetl` installed as well as an AWS controller. +To remove even those things proceed as follows: ```bash -juju destroy-controller -y lxd -sudo snap remove lxd +juju destroy-controller -y aws-k8s sudo snap remove juju +sudo snap remove kubectl ``` That's the end of this tutorial! From 7d0b335f0bb7e36dfe615aa816d31ce6eb757644 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 30 Nov 2018 11:46:59 -0500 Subject: [PATCH 162/311] swap out text for images due to wordwrapping --- src/en/tutorial-k8s-static-pv.md | 63 ++++++++++++-------------------- 1 file changed, 24 insertions(+), 39 deletions(-) diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md index 62dacae2a..42551b6fc 100644 --- a/src/en/tutorial-k8s-static-pv.md +++ b/src/en/tutorial-k8s-static-pv.md @@ -237,12 +237,7 @@ kubectl -n k8s-model get sc,pv,pvc Our example's output: -```no-highlight -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -persistentvolume/op1 1032Mi RWO Retain Available k8s-model-juju-operator-storage 7m21s -persistentvolume/vol1 100Mi RWO Retain Available k8s-model-juju-unit-storage 7m16s -Persistentvolume/vol2 100Mi RWO Retain Available k8s-model-juju-unit-storage 7m12s -``` +![kubectl -n k8s-model get sc-pv-pvc first][volumes] Notice how our model name of 'k8s-model' can be passed to `kubectl`. When the Juju model was added a Kubernetes "namespace" was set up with the same name. @@ -263,46 +258,43 @@ have taken. The two storage classes are 'k8s-model-juju-operator-storage' and Naturally, then, during the creation process of a storage pool the storage class is referenced. However, Juju will automatically prepend the name of the current model (or that of the model specified via `-m`) to the referenced -storage class name. Omit, therefore, the model name portion of the storage -class when creating the pool. +storage class name when it informs the cluster. Omit, therefore, the model name +portion of the storage class when creating the pool. The storage pool name for operator storage *must* be called 'operator-storage' while the pool name for charm storage is arbitrary. Here, we'll call it -'k8s-pool'. It is the charm storage pool name that will be called during the -deployment of a charm. +'k8s-pool'. It is the storage pool name that will be referenced at charm +deployment time. For static volumes, the Kubernetes "storage provisioner" is called 'kubernetes.io/no-provisioner'. Finally, the "storage provider" is called 'kubernetes'. This provider became -available once the Kubernetes model was added. +available upon the addition of the Kubernetes model. + +Putting this all together, then, our two storage pools are created as shown +below. -Putting this all together, then, our two storage pools are created in this way: +Operator storage pool: ```bash juju create-storage-pool operator-storage kubernetes \ storage-class=juju-operator-storage \ storage-provisioner=kubernetes.io/no-provisioner -juju create-storage-pool k8s-pool kubernetes \ - storage-class=juju-unit-storage \ - storage-provisioner=kubernetes.io/no-provisioner ``` -Perform a verification by listing all current storage pools with the -`storage-pools` command: +Charm storage pool: ```bash -juju storage-pools +juju create-storage-pool k8s-pool kubernetes \ + storage-class=juju-unit-storage \ + storage-provisioner=kubernetes.io/no-provisioner ``` -Our example's output: +Perform a verification by listing all current storage pools with the +`storage-pools` command. Our example's output: -```no-highlight -Name Provider Attrs -k8s-pool kubernetes storage-class=juju-unit-storage storage-provisioner=kubernetes.io/no-provisioner -kubernetes kubernetes -operator-storage kubernetes storage-class=juju-operator-storage storage-provisioner=kubernetes.io/no-provisioner -``` +![juju storage-pools][storage-pools] Almost there! @@ -358,20 +350,7 @@ kubectl -n k8s-model get sc,pv,pvc New sample output: -```no-highlight -NAME PROVISIONER AGE -storageclass.storage.k8s.io/k8s-model-juju-operator-storage kubernetes.io/no-provisioner 3m2s -storageclass.storage.k8s.io/k8s-model-juju-unit-storage kubernetes.io/no-provisioner 2m30s - -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -persistentvolume/op1 1032Mi RWO Retain Bound k8s-model/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 k8s-model-juju-operator-storage 7m5s -persistentvolume/vol1 100Mi RWO Retain Bound k8s-model/juju-database-0-juju-mariadb-k8s-0 k8s-model-juju-unit-storage 6m54s -persistentvolume/vol2 100Mi RWO Retain Available k8s-model-juju-unit-storage 6m51s - -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -persistentvolumeclaim/juju-database-0-juju-mariadb-k8s-0 Bound vol1 100Mi RWO k8s-model-juju-unit-storage 2m30s -persistentvolumeclaim/mariadb-k8s-operator-volume-juju-operator-mariadb-k8s-0 Bound op1 1032Mi RWO k8s-model-juju-operator-storage 3m2s -``` +![kubectl -n k8s-model get sc-pv-pvc][sc-pv-pvc] Awesome. @@ -433,3 +412,9 @@ go through this Ubuntu tutorial: [install]: ./reference-install.md [tutorial-microk8s]: ./tutorial-microk8s.md [kubernetes-hostpath]: https://kubernetes.io/docs/concepts/storage/volumes/#hostpath + + + +[storage-pools]: https://assets.ubuntu.com/v1/26ff0c70-storage-pools-2.png +[sc-pv-pvc]: https://assets.ubuntu.com/v1/a8cc75dd-sc-pv-pvc-2.png +[volumes]: https://assets.ubuntu.com/v1/34f93a4b-volumes-2.png From dc37dd32e2a2b02383bcfad12384033f94cfab86 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 30 Nov 2018 15:52:52 -0500 Subject: [PATCH 163/311] polish --- src/en/clouds-k8s.md | 39 +++++++--------------------- src/en/clouds.md | 2 ++ src/en/tutorial-k8s-static-pv.md | 44 +++++++++++++++----------------- src/en/tutorial-microk8s.md | 15 +++++------ 4 files changed, 38 insertions(+), 62 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index c6418b29f..94e3eb16f 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -13,10 +13,10 @@ Kubernetes ("k8s") provides a flexible architecture for managing containerised applications at scale. See the [Kubernetes documentation][upstream-kubernetes-docs] for more information. -Juju has the ability to add a Kubernetes cluster to its known list of clouds -and then treat it like it does any other cloud. There are some exceptions to -this and these are covered in the next section. In addition, -Kubernetes-specific charms are needed. +Juju has the ability to add a Kubernetes cluster to its known list of clouds, +thereby treating the cluster like it does any other cloud. There are some +differences to working with such a cloud and they are covered in the next +section. This document refers to page [Persistent storage and Kubernetes][charms-storage-k8s] in a few places. You @@ -48,6 +48,8 @@ list of known clouds. The `scale-application` command is used to scale a Kubernetes cluster. The `add-unit` and `remove-unit` commands do not apply to a Kubernetes model. +A Kubernetes cloud also requires Kubernetes-specific charms. + ## Using Kubernetes with Juju First off, a Kubernetes cluster will be required. Essentially, you will use it @@ -154,10 +156,7 @@ kubectl create -f operator-storage.yaml kubectl create -f charm-storage-vol1.yaml ``` -For assistance with the contents of these files see section -[Statically provisioned volumes][charms-storage-k8s-static-pv]. - -There is also a tutorial on setting up static persistent volumes here: +For in-depth coverage on this topic see tutorial [Setting up static Kubernetes storage][tutorial-k8s-static-pv]. ### Create storage pools @@ -174,8 +173,7 @@ juju create-storage-pool k8s-pool kubernetes \ storage-provisioner=kubernetes.io/no-provisioner ``` -For details on creating storage pools see section -[Storage pool creation][charms-storage-k8s-pool-creation]. +The above tutorial also covers storage pool creation! ### Deploy a Kubernetes charm @@ -191,7 +189,7 @@ juju deploy cs:~wallyworld/mariadb-k8s --storage database=k8s-pool,10M The [Using Juju storage][charms-storage-juju-deploy] page covers the above syntax. -If you want to deploy a Kubernetes bundles see section +If you want to deploy a Kubernetes bundle see section [Kubernetes bundles][charms-bundles-k8s]. #### Configuration @@ -232,23 +230,6 @@ Keys 'juju-external-hostname' and 'juju-application-path' control how the application is exposed externally using a Kubernetes Ingress Resource in conjunction with the configured ingress controller (default: nginx). -## Inspect cluster storage objects - -List cluster storage objects such as storage classes (SC), persistent -volumes (PV), and persistent volume claims (PVC) in this way: - -```bash -kubectl -n k8s-model get sc,pv,pvc -``` - -Drill down into Kubernetes objects such as pods and PVCs with the following -commands: - -```bash -kubectl -n k8s-model describe pods -kubectl -n k8s-model describe pvc -``` - @@ -257,8 +238,6 @@ kubectl -n k8s-model describe pvc [kubernetes-cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator [charms-storage-k8s]: ./charms-storage-k8s.md -[charms-storage-k8s-static-pv]: ./charms-storage-k8s.md#statically-provisioned-volumes -[charms-storage-k8s-pool-creation]: ./charms-storage-k8s.md#storage-pool-creation [charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles [charms-storage-juju-deploy]: ./charms-storage.md#juju-deploy [tutorial-microk8s]: ./tutorial-microk8s.md diff --git a/src/en/clouds.md b/src/en/clouds.md index b92f84c46..67dd9add7 100644 --- a/src/en/clouds.md +++ b/src/en/clouds.md @@ -26,6 +26,7 @@ clouds are added. You can still get started by selecting your cloud here: - [Joyent][clouds-joyent] ***** - [LXD][clouds-lxd] (local) ***** - [LXD][clouds-lxd] (remote) + - [Kubernetes][clouds-k8s] - [VMware vSphere][clouds-vmware] - [OpenStack][clouds-openstack] - [MAAS][clouds-maas] @@ -216,6 +217,7 @@ Here are some examples of manually adding a cloud: [clouds-openstack]: ./help-openstack.md [clouds-maas]: ./clouds-maas.md [clouds-manual]: ./clouds-manual.md +[clouds-k8s]: ./clouds-k8s.md [yaml]: http://www.yaml.org/spec/1.2/spec.html [controllers-creating]: ./controllers-creating.md diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md index 42551b6fc..15119d8a8 100644 --- a/src/en/tutorial-k8s-static-pv.md +++ b/src/en/tutorial-k8s-static-pv.md @@ -31,13 +31,13 @@ The following criteria are assumed: - that you're using Ubuntu 18.04 LTS - that Juju (stable snap channel) is installed. See the - [Installing Juju][reference-install] page. + [Installing Juju][install] page. - that a credential for the 'aws' cloud has been added to Juju. See the [Credentials][credentials] page. -## Preliminaries +## Installing Kubernetes -Let's begin by creating a controller: +Let's begin by creating a controller. We're calling 'aws-k8s': ```bash juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore aws aws-k8s @@ -47,10 +47,8 @@ juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charms We've used the staging Charm Store in these instructions as the standard site does not yet support Kubernetes charms. -## Installing Kubernetes - -Deploy Kubernetes using the 'kubernetes-core' bundle, which will give us -a minimalist cluster: +Deploy Kubernetes using the 'kubernetes-core' bundle, which will give us a +minimalist cluster: ```bash juju deploy kubernetes-core @@ -129,7 +127,7 @@ k8s-model* k8s-cloud available 0 - admin 14 seconds ago Adding a model for a Kubernetes cloud unlocks the 'kubernetes' storage provider, which we'll refer to later. The output to `juju storage-pools` should -be: +now be: ```no-highlight Name Provider Attrs @@ -322,27 +320,26 @@ mariadb-k8s/0* active idle 10.1.69.14 3306/TCP In contrast to standard Juju behaviour, there are no machines listed here. +Here is one of the created charm storage persistent volumes in use: + ```bash juju storage --filesystem ``` +Output: + ```no-highlight Unit Storage id Id Provider id Mountpoint Size State Message mariadb-k8s/0 database/0 0 juju-database-0-juju-mariadb-k8s-0 /var/lib/mysql 38MiB attached ``` -```bash -juju storage --volume -``` - -```no-highlight -Unit Storage id Volume id Provider Id Size State Message -mariadb-k8s/0 database/0 0 vol1 409MiB attached -``` +We'll see the Provider id of 'juju-database-0-juju-mariadb-k8s-0' again in the +next section. ## Post-deploy cluster inspection -Let's see what has happened within the cluster by interrogating it again: +Let's see what has happened within the cluster due to the deployment of the +charm: ```bash kubectl -n k8s-model get sc,pv,pvc @@ -358,10 +355,12 @@ At the top we see that our two storage classes have been created and that they're both associated with the 'no-provisioner' provisioner. In the middle section it is clear that two of our volumes are being used -('Bound') and that one is available. +('Bound') and that one is available. The one that is used ('vol1') is claimed +by the same Provider id that we saw in the output of the `storage` command +above ('juju-database-0-juju-mariadb-k8s-0'). In the lower part we're told what has "claimed" the two used volumes. Each of -these claims have requested the use of the appropriate storage classes. +these claims have requested the use of the appropriate storage class. ## Removing configuration and software @@ -389,14 +388,11 @@ That's the end of this tutorial! ## Next steps -To explore using Juju with the MicroK8s project consider the following -tutorial: - +To explore using Juju with the MicroK8s project consider tutorial [Using Juju with MicroK8s][tutorial-microk8s]. To gain experience with a standalone (non-Juju) MicroK8s installation you can -go through this Ubuntu tutorial: - +go through Ubuntu tutorial [Install a local Kubernetes with MicroK8s][ubuntu-tutorial-kubernetes-microk8s]. diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index fe5ef9ec3..e38ddb0c9 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -215,13 +215,14 @@ microk8s.reset sudo snap remove microk8s ``` -This leaves us with LXD and Juju installed as well as a LXD controller. To -remove even those things proceed as follows: +This leaves us with LXD, Juju, and `kubectl` installed as well as a LXD +controller. To remove even those things proceed as follows: ```bash juju destroy-controller -y lxd sudo snap remove lxd sudo snap remove juju +sudo snap remove kubectl ``` That's the end of this tutorial! @@ -229,15 +230,13 @@ That's the end of this tutorial! ## Next steps To gain experience with a standalone (non-Juju) MicroK8s installation you can -go through this Ubuntu tutorial: - +go through Ubuntu tutorial [Install a local Kubernetes with MicroK8s][ubuntu-tutorial_kubernetes-microk8s]. As alluded to, some backing clouds may require you to create persistent -volumes, on top of creating the storage pools. The following tutorial will go -over this in detail: - -[Setting up static Kubernetes storage][tutorial-k8s-static-pv] +volumes, on top of creating the storage pools. Tutorial +[Setting up static Kubernetes storage][tutorial-k8s-static-pv] covers this in +detail: From c243f4a4b11820cf1286db8ce753b051d0f4c374 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sun, 2 Dec 2018 10:07:31 -0500 Subject: [PATCH 164/311] add to menu; rename title --- src/en/client.md | 2 +- src/en/metadata.yaml | 2 ++ src/en/models-upgrade-notes.md | 2 +- src/en/models-upgrade.md | 4 ++-- src/en/models.md | 2 +- src/en/troubleshooting-logs.md | 2 +- src/en/troubleshooting-upgrade.md | 2 +- 7 files changed, 9 insertions(+), 7 deletions(-) diff --git a/src/en/client.md b/src/en/client.md index a3eae6a7d..3704798b0 100644 --- a/src/en/client.md +++ b/src/en/client.md @@ -109,7 +109,7 @@ For more installation information and what versions are available, see [Reference: Installing Juju][reference-install]. !!! Note: - Models can also be upgraded. See the [Model upgrades][models-upgrade] + Models can also be upgraded. See the [Upgrading models][models-upgrade] page for guidance. diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 76cdc2a58..6f3cf072c 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -37,6 +37,8 @@ navigation: children: - title: Upgrading applications location: charms-upgrading.md + - title: Upgrading models + location: models-upgrade.md - title: Upgrading a machine series location: upgrade-series.md - title: Controller backups diff --git a/src/en/models-upgrade-notes.md b/src/en/models-upgrade-notes.md index 0641aa8d8..671b8f570 100644 --- a/src/en/models-upgrade-notes.md +++ b/src/en/models-upgrade-notes.md @@ -4,7 +4,7 @@ Title: Notes on upgrading Juju software # Notes on upgrading models This is an addendum to the main page describing Juju software upgrades: -[Model upgrades][models-upgrades]. +[Upgrading models][models-upgrades]. ## Agent software and related components diff --git a/src/en/models-upgrade.md b/src/en/models-upgrade.md index 48ec5ddd8..ee11726c8 100644 --- a/src/en/models-upgrade.md +++ b/src/en/models-upgrade.md @@ -1,6 +1,6 @@ -Title: Model upgrades +Title: Upgrading models -# Model upgrades +# Upgrading models A model is upgraded by upgrading the version of Juju running within it, in the form of machine agents and unit agents. Agents are pieces of software that run diff --git a/src/en/models.md b/src/en/models.md index 50e8f64b8..258c808b2 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -211,7 +211,7 @@ Common model management tasks are summarized below. running on every machine Juju creates. This upgrade process does not pertain to the Juju software package installed on a client system. - This is a complex subject. See [Model upgrades](./models-upgrade.html). + This is a complex subject. See [Upgrading models](./models-upgrade.html). diff --git a/src/en/troubleshooting-logs.md b/src/en/troubleshooting-logs.md index a2fa24780..30de944c1 100644 --- a/src/en/troubleshooting-logs.md +++ b/src/en/troubleshooting-logs.md @@ -56,7 +56,7 @@ reveals the agent's configuration file: ``` Consider keeping backups of these files, especially prior to upgrading the -agents. See [Model upgrades][models-upgrade]. +agents. See [Upgrading models][models-upgrade]. ### The debug-log command diff --git a/src/en/troubleshooting-upgrade.md b/src/en/troubleshooting-upgrade.md index c187f7df1..c669e8313 100644 --- a/src/en/troubleshooting-upgrade.md +++ b/src/en/troubleshooting-upgrade.md @@ -3,7 +3,7 @@ Title: Troubleshooting model upgrades # Troubleshooting model upgrades This section provides strategies and techniques to assist with broken model -upgrades. See the main [Model upgrades][models-upgrade] page for background +upgrades. See the main [Upgrading models][models-upgrade] page for background information. ## Case #1 - An agent does not restart (config) From c9e87258de667d9531af89b1b02954f2d7948a50 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 3 Dec 2018 14:41:57 -0500 Subject: [PATCH 165/311] update release notes and install page --- src/en/reference-install.md | 16 +++++------ src/en/reference-release-notes.md | 48 +++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 8 deletions(-) diff --git a/src/en/reference-install.md b/src/en/reference-install.md index 842e3f26e..b06f27ce4 100644 --- a/src/en/reference-install.md +++ b/src/en/reference-install.md @@ -7,9 +7,9 @@ distributions, macOS, and Windows. Development releases are also available for testing. Read on for how to install a stable or development version of Juju on your chosen platform. -## Version 2.4.6 +## Version 2.4.7 -The most recent stable version of Juju is 2.4.6. This is the version we +The most recent stable version of Juju is 2.4.7. This is the version we recommend for production use. See the [Release Notes][release-notes-2]. ### Ubuntu @@ -79,7 +79,7 @@ sudo snap install juju --classic For CentOS, you can download Juju from the following archive and install it manually: -[**juju-2.4.6-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) +[**juju-2.4.7-centos7.tar.gz**][juju-centos] ([md5][juju-centos-md5]) ### macOS @@ -100,7 +100,7 @@ brew upgrade juju A Windows installer is available for Juju and can be found here: -[**juju-setup-2.4.6-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) +[**juju-setup-2.4.7-signed.exe**][juju-win-signed] ([md5][juju-win-signed-md5]) ## Development releases @@ -167,9 +167,9 @@ instructions on how to build Juju from source. [snapcraft]: https://snapcraft.io [snapd-install]: https://snapcraft.io/docs/core/install [juju-new-bug]: https://bugs.launchpad.net/juju/+filebug -[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-setup-2.4.6-signed.exe -[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-setup-2.4.6-signed.exe/+md5 -[juju-centos]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-2.4.6-centos7.tar.gz -[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.6/+download/juju-2.4.6-centos7.tar.gz/+md5 +[juju-win-signed]: https://launchpad.net/juju/2.4/2.4.7/+download/juju-setup-2.4.7-signed.exe +[juju-win-signed-md5]: https://launchpad.net/juju/2.4/2.4.7/+download/juju-setup-2.4.7-signed.exe/+md5 +[juju-centos]: https://launchpad.net/juju/2.4/2.4.7/+download/juju-2.4.7-centos7.tar.gz +[juju-centos-md5]: https://launchpad.net/juju/2.4/2.4.7/+download/juju-2.4.7-centos7.tar.gz/+md5 [juju-launchpad-binaries]: https://launchpad.net/juju/+series [centos-and-other-linuxes]: #centos-and-other-linuxes diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index 730a7c223..668b6f7e4 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -5,6 +5,54 @@ Title: Juju Release Notes This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available [here][release-notes-1]. +^# Juju 2.4.7 + + This is a bug fix release and includes the fixes below: + + - [LP #1803484](https://bugs.launchpad.net/juju/2.4/+bug/1803484) - httpserver worker restart with controller-api-port gets stuck + - [LP #1778033](https://bugs.launchpad.net/juju/2.4/+bug/1778033) - juju stuck attaching storage to OSD + + For the full list of fixes and additions, see the + [2.4.7 milestone](https://launchpad.net/juju/+milestone/2.4.7). + + ## Enhancements + + **Disabling juju state metrics** + It was found that for some large controllers where the metrics were being + scraped into Prometheus, the collection of some metrics related to + information stored in the database was slow and causing timeouts. To deal + with this issue we have added a controller configuration feature to disable + the gathering of those metrics. + + This can be enabled using + + juju controller-config features=[disable-state-metrics] + + This can be set before upgrading to 2.4.7. The controller will need to be + restarted if it's done after upgrading. + + ## Get Juju + + The easiest way to install Juju is by using the `snap` package: + + sudo snap install juju --classic + + Those already using the 'stable' snap channel (the default as per the above + command) should be upgraded automatically. Other packages are available for a + variety of platforms (see the [install documentation][reference-install]). + + ## Feedback appreciated + + Let us know how you're using Juju or of any questions you may have. You can + join us on [Discourse][juju-discourse-forum], send us a message on Twitter + (hashtag `#jujucharms`), or talk to us in the `#juju` IRC channel on + freenode. + + ## More information + + To learn more about Juju visit our home page at + [https://jujucharms.com](https://jujucharms.com). + ^# Juju 2.4.6 This is primarily a bugfix release for the 2.4 series but comes with one new From 30a0b48094813cf39ec378d8d15ad1e5e0a445ae Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 3 Dec 2018 15:11:11 -0500 Subject: [PATCH 166/311] create a landing page for upgrading things; simplify menu --- src/en/developer-upgrade-charm.md | 2 +- src/en/metadata.yaml | 8 ++------ src/en/models-upgrade.md | 5 ----- src/en/upgrading.md | 25 +++++++++++++++++++++++++ 4 files changed, 28 insertions(+), 12 deletions(-) create mode 100644 src/en/upgrading.md diff --git a/src/en/developer-upgrade-charm.md b/src/en/developer-upgrade-charm.md index 6c283d9ba..494d057dd 100644 --- a/src/en/developer-upgrade-charm.md +++ b/src/en/developer-upgrade-charm.md @@ -1,7 +1,7 @@ Title: Upgrading a charm TODO: Completely devoid of CLI examples. Kindly add -# Upgrade a Charm +# Upgrading a charm A charm can be changed at runtime with the `upgrade-charm` command. By default, it changes to the latest available version of the same charm; if `--revision` diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 6f3cf072c..05c0a987a 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -35,12 +35,8 @@ navigation: - title: Administering Juju children: - - title: Upgrading applications - location: charms-upgrading.md - - title: Upgrading models - location: models-upgrade.md - - title: Upgrading a machine series - location: upgrade-series.md + - title: Upgrading + location: upgrading.md - title: Controller backups location: controllers-backup.md - title: Controller high availability diff --git a/src/en/models-upgrade.md b/src/en/models-upgrade.md index ee11726c8..6bb410823 100644 --- a/src/en/models-upgrade.md +++ b/src/en/models-upgrade.md @@ -10,10 +10,6 @@ on each machine spawned by Juju, including controllers. See the A model upgrade is performed with the `upgrade-model` command and acts on all machine and unit agents running on all machines in the model. -!!! Note: - The client can also be upgraded. See the [Juju client][client-upgrades] - page for how to do that. - Several noteworthy points regarding backups: - Upgrades must be applied to the 'controller' model before upgrading other @@ -81,7 +77,6 @@ A model upgrade that does not lead to 100% success will require attention. See -[client-upgrades]: client.md#client-upgrades [models-upgrade-notes]: models-upgrade-notes.md [controller-backups]: controllers-backup.md [concepts-agent]: juju-concepts.md#agent diff --git a/src/en/upgrading.md b/src/en/upgrading.md new file mode 100644 index 000000000..db74294b5 --- /dev/null +++ b/src/en/upgrading.md @@ -0,0 +1,25 @@ +Title: Upgrading + +# Upgrading + +There are a number of software components in the Juju universe that can be +upgraded. Please visit the page dedicated to the task you're interested in. + + - [Upgrading a machine series][upgrade-series] + This affects the series (release) of the underlying operating system of a + Juju machine, including a controller. + - [Upgrading models][upgrade-models] + This affects the version of Juju running on a Juju machine in the form of + machine agents and unit agents. + - [Upgrading a charm][upgrade-charm] + This affects the version of an already deployed charm. + - [Upgrading the client][upgrade-client] + This affects the version of the Juju client. + + + + +[upgrade-series]: ./upgrade-series.md +[upgrade-models]: ./models-upgrade.md +[upgrade-charm]: ./developer-upgrade-charm.md +[upgrade-client]: ./client.md#client-upgrades From 796d834c1adb7d43fe5555fec9cb340bd6143e8c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 4 Dec 2018 09:43:21 -0500 Subject: [PATCH 167/311] provide better link; include guidelines --- src/en/upgrading.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/en/upgrading.md b/src/en/upgrading.md index db74294b5..5f781e17f 100644 --- a/src/en/upgrading.md +++ b/src/en/upgrading.md @@ -1,4 +1,5 @@ Title: Upgrading +TODO: Provide specific examples of how one component upgrade influence another component upgrade # Upgrading @@ -11,15 +12,20 @@ upgraded. Please visit the page dedicated to the task you're interested in. - [Upgrading models][upgrade-models] This affects the version of Juju running on a Juju machine in the form of machine agents and unit agents. - - [Upgrading a charm][upgrade-charm] + - [Upgrading applications][upgrade-applications] This affects the version of an already deployed charm. - [Upgrading the client][upgrade-client] This affects the version of the Juju client. +There is no inherent reason to upgrade components at the same time or to +upgrade components in a specific order. What often dictates an upgrade is a +desired feature in a new version of one component. This may, either before or +after, necessitate the upgrade of another component. + [upgrade-series]: ./upgrade-series.md [upgrade-models]: ./models-upgrade.md -[upgrade-charm]: ./developer-upgrade-charm.md +[upgrade-applications]: ./charms-upgrading.md [upgrade-client]: ./client.md#client-upgrades From 06b0c6fe558e6dabc26a01d1c3c13680563f25a8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 4 Dec 2018 13:11:00 -0500 Subject: [PATCH 168/311] more details; add to main storage page --- src/en/charms-storage-k8s.md | 9 +++++++-- src/en/charms-storage.md | 34 +++++++++++++++++++++++++++++++--- 2 files changed, 38 insertions(+), 5 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 30c120e0a..5afee08fc 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -31,9 +31,13 @@ within Kubernetes itself). Juju-managed storage can be provisioned either dynamically or statically. +The topic of storage is covered in a non-Kubernetes context on the +[Using Juju Storage][charms-storage] page. + !!! Note: - The topic of storage is covered in a non-Kubernetes context on the - [Using Juju Storage][charms-storage] page. + Kubernetes charms are currently only available on the + [staging Charm Store][charm-store-staging] and are for developmental and + testing purposes only. ## Juju-managed storage @@ -265,5 +269,6 @@ with Juju-managed statically provisioned volumes. [kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ [#creating-storage-pools]: #creating-storage-pools [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 +[charm-store-staging]: https://staging.jujucharms.com [tutorial-microk8s]: ./tutorial-microk8s.md [#external-storage-and-storage-precedence-rules]: #external-storage-and-storage-precedence-rules diff --git a/src/en/charms-storage.md b/src/en/charms-storage.md index 41b766e51..2a310a07f 100644 --- a/src/en/charms-storage.md +++ b/src/en/charms-storage.md @@ -18,9 +18,6 @@ to the [PostgreSQL charm][charm-store-postgresql] and the The Ceph examples used here are based on the Ceph cluster described in the document [Installing Ceph][charms-storage-ceph]. -Using storage with Kubernetes is covered on the -[Persistent storage and Kubernetes][charms-storage-k8] page. - ## Storage management commands Outside of application deployment, Juju also has a wide array of storage @@ -545,6 +542,37 @@ juju deploy postgresql --storage pgdata=lxd,8G See [Using LXD with Juju][clouds-lxd] for how to use LXD in conjunction with Juju, including the use of ZFS as an alternative filesystem. +### Kubernetes (kubernetes) + +Kubernetes-based models have access to the 'kubernetes' storage provider, which +supports the following pool attributes: + +- **storage-class** + + The storage class for the Kubernetes cluster to use: + + - `juju-unit-storage` + - `juju-charm-storage` + - `microk8s-hostpath` + +- **storage-provisioner** + + The Kubernetes storage provisioner. For example: + + - `kubernetes.io/no-provisioner` + - `kubernetes.io/aws-ebs` + - `kubernetes.io/gce-pd` + +- **parameters.type** + + Extra parameters. For example: + + - `gp2` + - `pd-standard` + +Using storage with Kubernetes is covered on the +[Persistent storage and Kubernetes][charms-storage-k8] page. + #### Loop devices and LXD LXD (localhost) does not officially support attaching loopback devices for From 068f638551c632448c47d7a2775fb4bccd2406a5 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 4 Dec 2018 15:53:37 -0500 Subject: [PATCH 169/311] small improvements --- src/en/charms-storage-k8s.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 5afee08fc..9207401b9 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -131,7 +131,7 @@ created, they must also be manually removed. The storage class name for a statically provisioned volume must be prefixed with the name of the intended model. In the examples above, the model name is 'k8s-model'. The remainder of the name, for both operator and charm - storage, are fixed. This is explained again further on. + storage, are fixed. ## Storage pool creation From 6affba7cedaf07c3b754d0cc71d38bdfa13176b2 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 5 Dec 2018 11:09:33 -0500 Subject: [PATCH 170/311] finish --- src/en/charms-storage-k8s.md | 16 +--------------- src/en/clouds-k8s.md | 6 ++++++ src/en/tutorial-k8s-static-pv.md | 12 ++++++------ src/en/tutorial-microk8s.md | 26 ++++++++++---------------- 4 files changed, 23 insertions(+), 37 deletions(-) diff --git a/src/en/charms-storage-k8s.md b/src/en/charms-storage-k8s.md index 9207401b9..bfa1909cc 100644 --- a/src/en/charms-storage-k8s.md +++ b/src/en/charms-storage-k8s.md @@ -34,11 +34,6 @@ Juju-managed storage can be provisioned either dynamically or statically. The topic of storage is covered in a non-Kubernetes context on the [Using Juju Storage][charms-storage] page. -!!! Note: - Kubernetes charms are currently only available on the - [staging Charm Store][charm-store-staging] and are for developmental and - testing purposes only. - ## Juju-managed storage As mentioned, there are two types of persistent storage that Juju can manage: @@ -52,15 +47,7 @@ is not supported by Kubernetes. This situation therefore demands that volumes be set up prior to the creation of the storage pool. See [Types of volumes][kubernetes-supported-volume-types] for the list of -Kubernetes supported storage backends. This will inform you whether your -backing cloud can use dynamically provisioned volumes. As of time of writing, -the list of Juju-supported clouds that also have dynamic volume support are: - - - Amazon AWS - - Google GCE - - Microsoft Azure - - OpenStack - - VMware vSphere +Kubernetes supported storage backends. !!! Important: Static volumes are mainly intended for testing/prototyping. They need the @@ -269,6 +256,5 @@ with Juju-managed statically provisioned volumes. [kubernetes-classes]: https://kubernetes.io/docs/concepts/storage/storage-classes/ [#creating-storage-pools]: #creating-storage-pools [charm-store-staging-mariadb-k8s]: https://staging.jujucharms.com/u/wallyworld/mariadb-k8s/7 -[charm-store-staging]: https://staging.jujucharms.com [tutorial-microk8s]: ./tutorial-microk8s.md [#external-storage-and-storage-precedence-rules]: #external-storage-and-storage-precedence-rules diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 94e3eb16f..4fdc69227 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -50,6 +50,11 @@ The `scale-application` command is used to scale a Kubernetes cluster. The A Kubernetes cloud also requires Kubernetes-specific charms. +!!! Note: + Kubernetes charms are currently only available on the + [staging Charm Store][charm-store-staging] and are for developmental and + testing purposes only. + ## Using Kubernetes with Juju First off, a Kubernetes cluster will be required. Essentially, you will use it @@ -236,6 +241,7 @@ conjunction with the configured ingress controller (default: nginx). [kubernetes-core-charm]: https://jujucharms.com/kubernetes-core/ [ubuntu-tutorial_install-kubernetes-with-conjure-up]: https://tutorials.ubuntu.com/tutorial/install-kubernetes-with-conjure-up#0 [kubernetes-cdk-charm]: https://jujucharms.com/u/containers/canonical-kubernetes/ +[charm-store-staging]: https://staging.jujucharms.com [charm-store-staging-integrator]: https://staging.jujucharms.com/q/integrator [charms-storage-k8s]: ./charms-storage-k8s.md [charms-bundles-k8s]: ./charms-bundles.md#kubernetes-bundles diff --git a/src/en/tutorial-k8s-static-pv.md b/src/en/tutorial-k8s-static-pv.md index 15119d8a8..194fad01c 100644 --- a/src/en/tutorial-k8s-static-pv.md +++ b/src/en/tutorial-k8s-static-pv.md @@ -6,12 +6,12 @@ Title: Setting up static Kubernetes storage [Using Kubernetes with Juju][clouds-k8s]. See that page for background information.* -This short tutorial will show the steps required to create Kubernetes -persistent storage volumes for use with Juju. This is normally done when the -backing cloud you're using does not have a storage type that is supported -natively by Kubernetes. There is no reason, however, why you cannot use -statically provisioned volumes with any cloud. Here, we'll use AWS as our -backing cloud. Kubernetes does support AWS/EBS volumes (as shown +This tutorial will show the steps required to create Kubernetes persistent +storage volumes for use with Juju. This is normally done when the backing cloud +you're using does not have a storage type that is supported natively by +Kubernetes. There is no reason, however, why you cannot use statically +provisioned volumes with any cloud. Here, we'll use AWS as our backing cloud. +Kubernetes does support AWS/EBS volumes (as shown [here][kubernetes-supported-volume-types]; see 'AWSElasticBlockStore') but it does require the use of the [`aws-integrator`][charm-store-staging-aws-integrator] charm, which we'll cover diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index e38ddb0c9..0f131d7d9 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -17,6 +17,8 @@ on your personal workstation. Using it with Juju is icing on the cake! Since MicroK8s runs locally we'll be using a local LXD cloud to create a Juju controller. +This tutorial was written using MicroK8s `v1.13.0`. + ## Installing the software These instructions assume that you're using a fresh Ubuntu 18.04 LTS install, @@ -122,8 +124,8 @@ k8s-model* microk8s-cloud available 0 admin never connected ## Adding storage One of the benefits of using MicroK8s is that we get dynamically provisioned -storage out of the box. Below we have Juju create two storage pools, one for -operator storage and one for charm storage: +storage out of the box. Below we create two storage pools, one for operator +storage and one for charm storage: ```bash juju create-storage-pool operator-storage kubernetes storage-class=microk8s-hostpath @@ -146,7 +148,7 @@ The output to `juju status` should soon look like the following: ```no-highlight Model Controller Cloud/Region Version SLA Timestamp -k8s-model lxd microk8s-cloud 2.5-beta2 unsupported 18:55:56Z +k8s-model lxd microk8s-cloud 2.5-rc1 unsupported 18:55:56Z App Version Status Scale Charm Store Rev OS Address Notes mariadb-k8s active 1 mariadb-k8s jujucharms 13 kubernetes 10.152.183.209 @@ -190,8 +192,8 @@ K8s-model statefulset.apps/juju-operator-mariadb-k8s 1 1 140 ``` You can easily identify the changes, as compared to the initial output, by -scanning the left hand side for the model name we chose: 'k8s-model', which -ends up being the Kubernetes "namespace". +scanning the left hand side for our model name 'k8s-model', which ends up being +the Kubernetes "namespace". To get information on pod 'juju-mariadb-k8s-0' you need to refer to the namespace (since it's not the 'default' namespace) in this way: @@ -206,23 +208,15 @@ cluster information. ## Removing configuration and software -To remove all traces of MicroK8s and its configuration follow these steps: +To remove all traces of what we've done in this tutorial use the following +commands: ```bash -juju destroy-model -y --destroy-storage k8s-model -juju remove-k8s microk8s-cloud +juju kill-controller -y -t 0 lxd microk8s.reset sudo snap remove microk8s -``` - -This leaves us with LXD, Juju, and `kubectl` installed as well as a LXD -controller. To remove even those things proceed as follows: - -```bash -juju destroy-controller -y lxd sudo snap remove lxd sudo snap remove juju -sudo snap remove kubectl ``` That's the end of this tutorial! From e9554a77de5f387f634dd69e52df0544995cdfa9 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 5 Dec 2018 11:16:34 -0500 Subject: [PATCH 171/311] trivial --- src/en/tutorial-microk8s.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/en/tutorial-microk8s.md b/src/en/tutorial-microk8s.md index 0f131d7d9..3623ebd8d 100644 --- a/src/en/tutorial-microk8s.md +++ b/src/en/tutorial-microk8s.md @@ -213,6 +213,7 @@ commands: ```bash juju kill-controller -y -t 0 lxd +juju remove-cloud microk8s-cloud microk8s.reset sudo snap remove microk8s sudo snap remove lxd From b377c4e0d2cd255f4a06de389c54a7d473057258 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 6 Dec 2018 12:47:25 -0500 Subject: [PATCH 172/311] add new command --- src/en/charms-bundles.md | 194 +++++++++++++++++++++++++++++++++++++++ src/en/models.md | 14 +++ 2 files changed, 208 insertions(+) diff --git a/src/en/charms-bundles.md b/src/en/charms-bundles.md index e70356cc2..d41fb6bf2 100644 --- a/src/en/charms-bundles.md +++ b/src/en/charms-bundles.md @@ -479,6 +479,200 @@ applications: Local paths to resources can be useful, for example, in network restricted environments where a Juju controller is unable to contact the Charm Store. +## Comparing a bundle to a model + +To compare a model's configuration to that of a bundle the `diff-bundle` +command is used. + +Consider, for example, a model that has the below output to the `status` +command: + +```no-highlight +Model Controller Cloud/Region Version SLA Timestamp +docs lxd localhost/localhost 2.5-rc1 unsupported 05:22:22Z + +App Version Status Scale Charm Store Rev OS Notes +haproxy unknown 1 haproxy jujucharms 46 ubuntu +mariadb 10.1.37 active 1 mariadb jujucharms 7 ubuntu +mediawiki 1.19.14 active 1 mediawiki jujucharms 19 ubuntu + +Unit Workload Agent Machine Public address Ports Message +haproxy/0* unknown idle 2 10.86.33.28 80/tcp +mariadb/0* active idle 1 10.86.33.192 ready +mediawiki/0* active idle 0 10.86.33.19 80/tcp Ready + +Machine State DNS Inst id Series AZ Message +0 started 10.86.33.19 juju-dbf96b-0 trusty Running +1 started 10.86.33.192 juju-dbf96b-1 trusty Running +2 started 10.86.33.28 juju-dbf96b-2 bionic Running + +Relation provider Requirer Interface Type Message +haproxy:peer haproxy:peer haproxy-peer peer +mariadb:cluster mariadb:cluster mysql-ha peer +mariadb:db mediawiki:db mysql regular +mediawiki:website haproxy:reverseproxy http regular +``` + +Now say we have a bundle file `bundle.yaml` with these contents: + +```yaml +applications: + mediawiki: + charm: "cs:trusty/mediawiki-5" + num_units: 1 + options: + name: Central library + mysql: + charm: "cs:trusty/mysql-55" + num_units: 1 + options: + "binlog-format": MIXED + "block-size": 5 + "dataset-size": "512M" + flavor: distro + "ha-bindiface": eth0 + "ha-mcastport": 5411 + "max-connections": -1 + "preferred-storage-engine": InnoDB + "query-cache-size": -1 + "query-cache-type": "OFF" + "rbd-name": mysql1 + "tuning-level": safest + vip_cidr: 24 + vip_iface: eth0 +relations: + - - "mediawiki:db" + - "mysql:db" +``` + +Comparison of the currently active model with the bundle can be achieved in +this way: + +```bash +juju diff-bundle bundle.yaml +``` + +This produces an output of: + +```yaml +applications: + haproxy: + missing: bundle + mariadb: + missing: bundle + mediawiki: + charm: + bundle: cs:trusty/mediawiki-5 + model: cs:mediawiki-19 + series: + bundle: "" + model: trusty + options: + name: + bundle: Central library + model: null + mysql: + missing: model +machines: + "0": + missing: bundle + "1": + missing: bundle + "2": + missing: bundle +relations: + bundle-additions: + - - mediawiki:db + - mysql:db + model-additions: + - - haproxy:reverseproxy + - mediawiki:website + - - mariadb:db + - mediawiki:db +``` + +This informs us of the differences in terms of applications, machines, and +relations. For instance, compared to the model, the bundle is missing +applications 'haproxy' and 'mariadb', whereas the model is missing 'mysql'. +Both model and bundle utilise the 'mediawiki' application but they differ in +terms of configuration. There are also differences being reported in the +'machines' and 'relations' sections. We'll now focus on the 'machines' section +in order to demonstrate other features of the `diff-bundle` command. + +We can extend the bundle by including a bundle overlay. Consider an overlay +bundle file `changes.yaml` with these machine related contents: + +```yaml +applications: + mediawiki: + to: + - "2" + mysql: + to: + - "3" +machines: + "2": + series: trusty + constraints: "arch=amd64 cores=1" + "3": + series: trusty + constraints: "arch=amd64 cores=1" +``` + +Here, by means of the `--overlay` option, we can add this extra information to +the comparison, effectively inflating the configuration of the bundle: + +```bash +juju diff-bundle bundle.yaml --overlay changes.yaml +``` + +This changes the 'machines' section of the output to: + +```yaml +machines: + "0": + missing: bundle + "1": + missing: bundle + "2": + series: + bundle: trusty + model: bionic + "3": + missing: model +``` + +The initial comparison displayed a lack of all three machines in the bundle. By +adding machines '2' and '3' in the overlay the output now shows machines '0' +and '1' as missing in the bundle, machine '2' differs in configuration, and +machine '3' is missing in the model. + +As with the `deploy` command, there is the ability to map machines in the +bundle to those in the model. Below, the addition of `--map-machines=2=0,3=1` +makes, for the sake of the comparison, bundle machines 2 and 3 become model +machines 0 and 1, respectively: + +```bash +juju diff-bundle bundle.yaml --overlay changes.yaml --map-machines=2=0,3=1 +``` + +The 'machines' section now becomes: + +```yaml +machines: + "2": + missing: bundle +``` + +The bundle shows as only missing machine 2 now, which makes sense. + +The target bundle can also reside within in the online Charm Store. In that +case you would simply reference the bundle name, such as 'wiki-simple': + +```bash +juju diff-bundle wiki-simple +``` + ## Saving a bundle and next steps If you have created your own bundle you will probably want to save it. This is diff --git a/src/en/models.md b/src/en/models.md index 258c808b2..3fbf678b2 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -62,7 +62,16 @@ Common model management tasks are summarized below. For complete explanation and syntax, see the [command reference page](./commands.html#show-model) or the `juju help show-model` command. + + +^# Compare a bundle to a model + + Use the `diff-bundle` command to compare a model with a charm bundle: + + `juju diff-bundle [options] ` + + This topic is treated on the [Charm bundles][charms-bundles-diff] page. ^# Configure a model @@ -223,3 +232,8 @@ Common model management tasks are summarized below. paradigm by employing *cross model relations*. This is a complex subject. See [Cross model relations](./models-cmr.html). + + + + +[charms-bundles-diff]: ./charms-bundles.md#comparing-a-bundle-to-a-model From 05765db0f659b59e012a30fbe953cf4b96202d23 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 6 Dec 2018 14:57:26 -0500 Subject: [PATCH 173/311] add feature; quick format review --- src/en/actions.md | 114 ++++++++++++++++++++-------------- src/en/developer-debugging.md | 8 ++- 2 files changed, 72 insertions(+), 50 deletions(-) diff --git a/src/en/actions.md b/src/en/actions.md index 4a0acf189..77c7594fb 100644 --- a/src/en/actions.md +++ b/src/en/actions.md @@ -1,13 +1,14 @@ -Title: Juju actions +Title: Working with actions -# Juju Actions +# Working with actions Juju charms can describe *actions* that users can take on deployed applications. Actions are scripts that can be triggered on a unit via the command line. -Parameters for an action are passed as a map, either defined in a YAML file -or given through the UI, and are validated against the schema defined in -actions.yaml. See [Actions for the charm author][charmactions] for more information. +Parameters for an action are passed as a map, either defined in a YAML file or +given through the UI, and are validated against the schema defined in +actions.yaml. See [Actions for the charm author][dev-actions] for more +information. The following commands are specified for dealing with actions: @@ -19,9 +20,9 @@ The following commands are specified for dealing with actions: ## Action commands -### `juju actions` +### `actions` -List the actions defined for a service. +Lists the actions defined for a service. For example, with the 'git' charm deployed, you can see which actions it supports with the following command: @@ -48,11 +49,10 @@ remove-repo Remove a git repository. remove-repo-user Revoke a user's permissions to access a repository. remove-user Remove a user. ``` -To show the full schema for all the actions on a service, append the `--schema` -argument to the `actions` command. -For example, here's the beginning of the output from -`juju actions git --schema --format yaml`: +To show the full schema for all the actions on a service, append the `--schema` +argument to the `actions` command. For example, here's the beginning of the +output from `juju actions git --schema --format yaml`: ```bash add-repo: @@ -70,25 +70,27 @@ add-repo: ``` !!! Note: - the full schema is under the `properties` key of the root Action. Juju - Actions rely on [JSON-Schema][jsonschema] for validation. The - top-level keys shown for the Action (`description` and `properties`) may - include future additions to the feature. + The full schema is under the `properties` key of the root action. Actions + rely on [JSON-Schema][jsonschema] for validation. The top-level keys shown + for the action (`description` and `properties`) may include future + additions to the feature. + +### `run-action` -### `juju run-action` +Triggers an action. -Trigger an action. This command takes a unit (or multiple units) as an argument -and returns an ID for the action. The ID can be used with `juju -show-action-output ` or `juju show-action-status `. +This command takes a unit (or multiple units) as an argument and returns an ID +for the action. The ID can be used with `juju show-action-output ` or +`juju show-action-status `. If an action requires parameters, these can be passed directly. For example, we could create a new 'git' repository by triggering the 'add-repo' action and following this with the name we'd like to give the new repository: - ```bash juju run-action git/0 add-repo repo=myproject ``` + This will return the ID for the new action: ```bash @@ -102,10 +104,17 @@ application). So if there were two git units you can also do: juju run-action git/0 git/1 add-repo repo=myproject ``` -When running short-lived actions from the command line, it is more convenient to -add the `--wait` option to this command. This causes the Juju client to wait for -the action to run, and then return the results and other information in YAML -format. +To run an action on an application leader append the string "/leader" to the +application name, like this: + +```bash +juju run-action postgresql/leader switchover --string-args master=postgresql/1 +``` + +When running short-lived actions from the command line, it is more convenient +to add the `--wait` option to this command. This causes the Juju client to wait +for the action to run, and then return the results and other information in +YAML format. For example, running the command: @@ -136,13 +145,14 @@ For actions which may take longer to return, it is also possible to specify a or nanoseconds(ns). In this case, if the action has completed before the specified period is up, it will return the results as before. If the action has not completed, the command will simply return the id and status, enabling the -user to continue issuing commands. E.g.: +user to continue issuing commands. For instance: ```bash juju run-action git/0 list-repos --wait=10ns ``` -Ten nanoseconds isn't much time to get anything done, so in this case the output -will be similar to: + +Ten nanoseconds isn't much time to get anything done, so in this case the +output will be similar to: ```bash action-id: 10fb05d9-d220-4a07-825e-a1258b1a868b @@ -152,13 +162,15 @@ timing: ``` You can also set parameters indirectly via a YAML file, although you can -override the parameters within the file by providing them directly. +override those parameters by providing them directly. *Example params.yaml:* + ```yaml repo: myproject sure: no ``` + With the above example `params.yaml` file, we could remove the `myproject` git repository with the following command: @@ -168,8 +180,8 @@ juju run-action git/0 remove-repo --wait --params=params.yaml sure=yes If you have an action that requires multiple lines, use YAML quoting to make sure the whitespace is not collapsed into one line, like in this example where -`foo` is an action and the parameter `bar` is defined in the `actions.yaml` file -shown just after the example: +`foo` is an action and the parameter `bar` is defined in the `actions.yaml` +file shown just after the example: ```bash juju run-action unit/0 foo bar="'firstline @@ -182,6 +194,7 @@ YAML quoting uses both single ' and double " quotes to surround the part that should not be moved to one line. *Example actions.yaml:* + ```yaml #!/usr/bin/python3 @@ -192,10 +205,11 @@ with open("/tmp/out", mode='w') as out: sys.exit(0) ``` -### `juju show-action-output` +### `show-action-output` -Shows the results returned from an action with the given ID. To -see the output from the `add-repo` action we executed earlier, for example, +Shows the results returned from an action with the given ID. + +To see the output from the `add-repo` action we executed earlier, for example, we'd enter the following: ```bash @@ -203,9 +217,9 @@ juju show-action-output 3a7cc626-4c4c-4f00-820f-f881b79586d10 ``` This will return something like the following: + - + ```no-highlight results: dir: /var/git/myproject.git @@ -215,19 +229,22 @@ timing: enqueued: 2018-06-18 13:46:11 +0000 UTC started: 2018-06-18 13:46:11 +0000 UTC ``` -### `juju show-action-status` -Query the status of an action. For example, We could check on the progress of git's -`add-repo` action with the following command: +### `show-action-status` + +Queries the status of an action. + +For example, We could check on the progress of git's `add-repo` action with the +following command: ```bash juju show-action-status 3a7cc626-4c4c-4f00-820f-f881b79586d1 ``` + This will output the status of the action, shown here as 'completed': - + ```no-highlight actions: - id: 3a7cc626-4c4c-4f00-820f-f881b79586d1 @@ -237,11 +254,11 @@ actions: There are 5 different values for the status of an action: -- **pending**; the default status when an action is first queued. -- **running**; the action is currently running. -- **completed**; the action ran to completion as intended. -- **failed**; the action did not complete successfully. -- **cancelled**; the action was cancelled before being run. + - **pending** - the default status when an action is first queued. + - **running** - the action is currently running. + - **completed** - the action ran to completion as intended. + - **failed** - the action did not complete successfully. + - **cancelled** - the action was cancelled before being run. ### Debugging actions @@ -258,10 +275,11 @@ use: juju debug-hooks git/0 add-repo ``` -Learn more about debugging Juju charms in [Debugging hooks][devdebug]. +Learn more about debugging charms in [Debugging hooks][dev-debugging]. + -[charmactions]: ./authors-charm-actions.html [jsonschema]: http://json-schema.org -[devdebug]: ./developer-debugging.html +[dev-actions]: ./authors-charm-actions.md +[dev-debugging]: ./developer-debugging.md diff --git a/src/en/developer-debugging.md b/src/en/developer-debugging.md index 78f394a03..51b67a70d 100644 --- a/src/en/developer-debugging.md +++ b/src/en/developer-debugging.md @@ -1,4 +1,5 @@ Title: Debugging charm hooks +TODO: Critical: review and reformatting required # Debugging charm hooks @@ -100,7 +101,7 @@ use: juju debug-hooks git/0 add-repo ``` -Learn more about actions in [Juju actions][actions]. +Learn more about actions in [Working with actions][actions]. ## Running a debug session @@ -332,4 +333,7 @@ hand. Here are some of the ones you may find useful: You can get more info on tmux and its commands at the [relevant Ubuntu manpage entry.](http://manpages.ubuntu.com/manpages/trusty/man1/tmux.1.html) -[actions]: ./actions.html "Juju actions" + + + +[actions]: ./actions.md From 3654ba8a6c5e95435171c4423da26d9caefce3fe Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 7 Dec 2018 11:11:45 -0500 Subject: [PATCH 174/311] add --classic for the snap --- src/en/tools-charm-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/tools-charm-tools.md b/src/en/tools-charm-tools.md index 15ad5dd68..8868b7cda 100644 --- a/src/en/tools-charm-tools.md +++ b/src/en/tools-charm-tools.md @@ -13,7 +13,7 @@ Charm Tools can be installed on various platforms with the use of To install the Charm Tools on Ubuntu: ```bash -sudo snap install charm +sudo snap install charm --classic ``` To install on other Linux distributions see the upstream From cdf004ba3845186565984cd421734f0cb824fc8b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 11 Dec 2018 10:14:03 -0500 Subject: [PATCH 175/311] add new page --- src/en/tut-users.md | 2 ++ src/en/tutorial-multiuser.md | 10 ++++++++++ 2 files changed, 12 insertions(+) create mode 100644 src/en/tutorial-multiuser.md diff --git a/src/en/tut-users.md b/src/en/tut-users.md index 7c4ff3c2d..95fc650bd 100644 --- a/src/en/tut-users.md +++ b/src/en/tut-users.md @@ -1,6 +1,8 @@ Title: A multi-user cloud TODO: change screenshot username from degville to newuser add link to a table showing permissions for each type of user + General reivew and abstract linking + Consider renaming file to tutorial-multiuser-cloud.md # A multi-user cloud diff --git a/src/en/tutorial-multiuser.md b/src/en/tutorial-multiuser.md new file mode 100644 index 000000000..67bf0760e --- /dev/null +++ b/src/en/tutorial-multiuser.md @@ -0,0 +1,10 @@ +Title: Working with multiple users + +# Working with multiple users + +*This is a tutorial in connection with the multi-user feature set of Juju.* + + + + + From 585316047a22f577e58f41f732766cbd0348c48c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 14:33:18 -0500 Subject: [PATCH 176/311] begin refactor --- src/en/controllers-backup.md | 10 +-- src/en/multiuser.md | 79 ++++++++++++++++++++ src/en/users-auth.md | 2 +- src/en/users-creating.md | 87 ++-------------------- src/en/users-misc.md | 48 +++++++++++++ src/en/users.md | 135 +++++++++++++++++++---------------- 6 files changed, 212 insertions(+), 149 deletions(-) create mode 100644 src/en/multiuser.md create mode 100644 src/en/users-misc.md diff --git a/src/en/controllers-backup.md b/src/en/controllers-backup.md index 3fc80a319..db4429500 100644 --- a/src/en/controllers-backup.md +++ b/src/en/controllers-backup.md @@ -99,11 +99,11 @@ The optional note is exposed via the `show-backup` command detailed below. The following commands are available for managing backups (apart from restoring): - - `juju backups` - - `juju show-backup` - - `juju download-backup` - - `juju upload-backup` - - `juju remove-backup` + - `backups` + - `show-backup` + - `download-backup` + - `upload-backup` + - `remove-backup` #### `juju backups` diff --git a/src/en/multiuser.md b/src/en/multiuser.md new file mode 100644 index 000000000..c0f32d4b9 --- /dev/null +++ b/src/en/multiuser.md @@ -0,0 +1,79 @@ +Title: Using Juju with multiple users + +# Using Juju with multiple users + +Juju has an internal user framework that allows for the sharing of controllers +and models. To achieve this, a Juju user can be created that is of a certain +type; be granted specific permissions; and be authenticated in a certain way. + +[User types][users] + +# Creating users + +A user is added to a controller by the controller administrator. This process +yields a text string that encodes information about the user and the +controller. This string is supplied to the intended operator who will use it to +*register* the controller using their own Juju client. + +The user will be asked to enter an arbitrary (but hopefully meaningful) name to +the controller as well as create a password for themselves. The controller name +needs to be unique within the context of the client. The user's password is +stored on the controller. + +!!! Note: + Controller registration (and any other Juju operations that involves + communication between a client and a controller) necessitates the client be + able to contact the controller over the network on TCP port 17070. In + particular, if using a LXD-based cloud, network routes need to be in place + (i.e. to contact the controller LXD container the client traffic must be + routed through the LXD host). + +## User creation and controller registration + +To create user 'mat' the controller administrator uses the `add-user` command: + +```bash +juju add-user mat +``` + +This will produce output similar to: + +```no-highlight +User "mat" added +Please send this command to mat: + juju register ME0TA21hdDAWExQxMC4xNDkuMTMzLjIwOToxNzA3MAQg7D-RDR8cnioqd7ctEoCjyDzaprK4wXodvfMBBrgBUKETDGx4ZC1iaW9uaWMtMQAA + +"mat" has not been granted access to any models. You can use "juju grant" to grant access. +``` + +The administrator provides the command (manually) to the intended operator, who +will execute it: + +```bash +juju register ME0TA21hdDAWExQxMC4xNDkuMTMzLjIwOToxNzA3MAQg7D-RDR8cnioqd7ctEoCjyDzaprK4wXodvfMBBrgBUKETDGx4ZC1iaW9uaWMtMQAA +``` + +Sample user session: + + +```no-highlight +Enter a new password: +Confirm password: +Enter a name for this controller [lxd-bionic-1]: lxd-bionic-1 +Initial password successfully set for mat. + +Welcome, mat. You are now logged into "lxd-bionic-1". + +There are no models available. You can add models with +"juju add-model", or you can ask an administrator or owner +of a model to grant access to that model with "juju grant". +``` + +The name of the original controller, in this case 'lxd-bionic-1', is offered as +a default controller name. + + + + + +[users]: ./users.md diff --git a/src/en/users-auth.md b/src/en/users-auth.md index 6441f236a..630e738c2 100644 --- a/src/en/users-auth.md +++ b/src/en/users-auth.md @@ -34,7 +34,7 @@ cloud-backed resource. They are not related to Juju users themselves in any way. Credentials added to Juju remain local to the system user (on Ubuntu: `~/.local/share/juju/credentials.yaml`). -See [Cloud credentials][credentials] for more on this topic. +See [Credentials][credentials] for more on this topic. ## SSH access diff --git a/src/en/users-creating.md b/src/en/users-creating.md index 1dca34e10..2be1510c0 100644 --- a/src/en/users-creating.md +++ b/src/en/users-creating.md @@ -1,88 +1,18 @@ Title: Creating Juju users -# Creating users -A regular user is added to a controller by the controller administrator. This -process yields an alphanumeric text string that encodes information about the -user and the controller. This string is supplied (manually at this time) to the -corresponding (real) person who will use it to *register* with the controller -using their own client system. The user will be asked to enter an arbitrary -(but hopefully meaningful) name to the controller as well as create a password -for themselves. The controller name needs to be unique within the context of -the local (operating system) user account. The user's password is stored on the -controller. -!!! Note: - A "client system" is a computer, such as an Ubuntu system, that is on - the network and has Juju installed. +# Lost tokens -At this stage, the user is registered to a controller and is allowed to perform -the following additional actions (in the context of the controller): - - - List controllers (`juju controllers`) - - Show controller details (`juju show-controller`) - - List enabled controller users (`juju users`) - - Show details for controller users (`juju show-user`) - -To do anything further the user must wait to be granted access to a model by -the administrator. See [Users and models](./users-models.html). - -!!! Note: - User registration (and any other Juju operations that involves - communication between a client system and a controller) necessitates the client - be able to contact the controller over the network on TCP port 17070. In - particular, if using the LXD provider, network routes need to be in place (i.e. - to contact the LXD controller container the client traffic must be routed - through the LXD host). - - -## User creation and registration - -To create user 'jon' (in the current controller): - -```bash -juju add-user jon -``` - -Which will produce output similar to: - -```no-highlight -Please send this command to jon:    juju register -MD4TA2ppbTAVExMxMC4xOTUuMTAuMTMwOjE3MDcwBCDENImZEDvYcWLU1USgaUJQXhWR98JNLWcbS0-MiW6NiQA= - -"jon" has not been granted access to any models. You can use "juju grant" to -grant access. -``` - -Send the command to Jon. The registration string contained in the command you -send encodes the addresses of the controller. All Jon must do is enter the -command on a client system with Juju installed and that is able to access the -target controller's network: - -```bash -juju register -MD4TA2ppbTAVExMxMC4xOTUuMTAuMTMwOjE3MDcwBCDENImZEDvYcWLU1USgaUJQXhWR98JNLWcbS0-MiW6NiQA= -``` - -The user will then be prompted to enter and confirm a password, and also supply a unique name for the controller. - -### Lost tokens - -If a situation occurs where the registering token fails to work for some reason, or is -lost, a new token can be generated by the admin user with the `change-user-password` command. -For example, to generate a new token for 'jon', the admin user can use this command with the '--reset' switch: +If a situation occurs where the registering token fails to work for some +reason, or is lost, a new token can be generated by the admin user with the +`change-user-password` command. For example, to generate a new token for +'jon', the admin user can use this command with the '--reset' switch: ```bash juju change-user-password jon --reset ``` -This should generate output like this: - -``` -Password for "jon" has been reset. -Ask the user to run: - juju register MFsTBHBsb3AwKRMSNTQuODIuMTM0LjY2OjE3MDcwExMxMC4xNTAuOTAuMTc4OjE3MDcwBCAE0XRp7xXV9AMRpK9L89nWn-jtXn7qalK47AtVQhXPQhMGMjJ0ZXN0 -``` The previous token will now be invalid, and the user should register with the new token. @@ -90,9 +20,8 @@ the new token. ## Logins and logouts On any given client system, each controller that shows up with -`juju controllers` accepts a single login; a logout is necessary before -logging in to the same controller. Note that a logout of a user on one client -does not affect the same user session possibly underway on a separate client. +`juju controllers` accepts a single login; a logout is necessary before logging +in to the same controller. A newly-registered user is automatically logged in to a session. To log out of the current Juju user session: @@ -117,5 +46,3 @@ juju whoami The command `juju show-user` can also be used to get the current user, in addition to other information on the user. - - diff --git a/src/en/users-misc.md b/src/en/users-misc.md new file mode 100644 index 000000000..2be1510c0 --- /dev/null +++ b/src/en/users-misc.md @@ -0,0 +1,48 @@ +Title: Creating Juju users + + + + +# Lost tokens + +If a situation occurs where the registering token fails to work for some +reason, or is lost, a new token can be generated by the admin user with the +`change-user-password` command. For example, to generate a new token for +'jon', the admin user can use this command with the '--reset' switch: + +```bash +juju change-user-password jon --reset +``` + +The previous token will now be invalid, and the user should register with +the new token. + +## Logins and logouts + +On any given client system, each controller that shows up with +`juju controllers` accepts a single login; a logout is necessary before logging +in to the same controller. + +A newly-registered user is automatically logged in to a session. To log out of +the current Juju user session: + +```bash +juju logout +``` + +And to log back in, either on the same client system or not, using the same +user we added earlier: + +```bash +juju login -u jon +``` + +Once a user logs in they become the current user. The following is a quick way +to determine the current user (as well as the current controller and model): + +```bash +juju whoami +``` + +The command `juju show-user` can also be used to get the current user, in +addition to other information on the user. diff --git a/src/en/users.md b/src/en/users.md index be15d081a..0445e21b1 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -1,51 +1,52 @@ -Title: Understanding users -TODO: User abilities, especially owners and regular users - Critical: review required +Title: User types +# User types -# Understanding users +*This is in connection with the [Using Juju with multiple users][multiuser] +page. See that resource for background information.* -There are 3 kinds of Juju users: controller administrators, model owners, and -regular users. Each user, no matter the kind, is associated with a controller. -In particular, the namespace for users are controller-centric; names can be -duplicated across controllers. +There are three kinds of Juju users: controller administrators, model owners, +and regular users. Each user, no matter the kind, is associated with a +controller. In particular, the namespace for users are controller-centric; +names can be duplicated across controllers. Juju users are not related in any way to the localhost system users; they are purely Juju constructs. A *controller administrator* is a user who has access to the controller model. -This Juju user is called 'admin' and is set up as part of the -controller creation step. Practically, this set of users is comprised of the -controller creator and any user the creator/initial_admin has granted write -access to the 'controller' model. There is no overarching -"Juju administrator" since multiple controllers, and therefore multiple -administrators, are possible. +This Juju user is called 'admin' and is set up as part of the controller +creation step. Practically, this set of users is comprised of the controller +creator and any user the creator/initial_admin has granted write access to the +'controller' model. There is no overarching "Juju administrator" since multiple +controllers, and therefore multiple administrators, are possible. A *model owner* is the model creator or a user who has been designated as such during the model creation process. A *regular user* is one who is neither an administrator nor a model owner. Such a user requires access to a model in order to do anything at the Juju level. -Note that although deemed "regular", such a user is far from ordinary since they -can marshal the vast resources of the backing cloud and deploy complex +Note that although deemed "regular", such a user is far from ordinary since +they can marshal the vast resources of the backing cloud and deploy complex applications. - ## User abilities The different Juju user types have different abilities based on permissions. -They are outlined below. For completeness, the abilities of system (localhost) -users are also included. +They are outlined below. For completeness, the abilities of system users and +newly-created users are also included. + +### System users -Actions available to a system user: +Actions available to a system user and the corresponding Juju commands: -- Access general help (`juju help`) -- List supported cloud types (`juju clouds`) -- Show details on each cloud type (`juju show-cloud`) -- Register with a controller (`juju register`) -- Add credentials (`juju add-credential` and `juju autoload-credentials`) -- List cloud credentials (`juju credentials`) -- Create controllers (`juju bootstrap`) + - Access help (`help`) + - List supported cloud types (`clouds`) + - Show details on each cloud type (`show-cloud`) + - Connect to a controller (`register`) + - Add credentials (`add-credential` and `autoload-credentials`) + - List credentials (`credentials`) + - Create controllers (`bootstrap`) + - Log in to a controller (`login`) Once a system user has created a controller they are provided automatically, at the Juju level, with an administrator of that controller and inherit all the @@ -54,52 +55,60 @@ privileges of that user type (see below). Since any system user can add credentials and create controllers, it is conceivable that multiple controllers exist that use the same cloud resource (public cloud account). Although this will work with Juju, it is a policy -decision on the part of those who use Juju as to whether this should be -allowed. - -See [Controllers](./controllers.html) for information on controllers. - -### Administrators -Only an administrator has the power to perform these actions (in -the context of their controller): - -- Add users (`juju add-user`) -- Disable users (`juju disable-user`) -- Enable previously disabled users (`juju enable-user`) -- Create models (`juju create-model`) -- Grant user access to models (`juju grant`) -- Revoke user access from models (`juju revoke`) -- Remove models (`juju destroy-model`) -- Remove the controller (`juju destroy-controller`) -- Upgrade any model (`juju upgrade-model`) -- Maintenance operations (e.g.: backups) +decision as to whether this should be allowed. + +### Newly-created users + +A newly-created user is automatically granted login access to the controller. +Once logged in, the user is allowed to perform the following additional +actions: + + - List the user (`users`) + - Show details for the user (`show-user`) + - Log out of a controller (`logout`) + +To do anything further the user must be granted some level of access to a model +or be given superuser access to the controller. + +### Controller administrators + +Only a controller administrator (the "admin") has the power to perform these +actions (in the context of their controller): + + - Add users (`add-user`) + - Disable users (`disable-user`) + - Enable previously disabled users (`enable-user`) + - Create models (`create-model`) + - Grant user access to models (`grant`) + - Revoke user access from models (`revoke`) + - Remove models (`destroy-model`) + - Remove the controller (`destroy-controller` or `kill-controller`) + - Upgrade any model (`upgrade-model`) + - Manage controller backups (e.g. `create-backup`) ### Model owners + A model owner has the power to list users who have access to the model they own -(`juju users mymodel`) as well as upgrade their model (`juju upgrade-model`). +(`users`) as well as upgrade their model (`upgrade-model`). ### Regular users + The ability of a regular user depends on the model access rights (read-only or -write) they have been given. +write) they have been granted. For read-only access, the user can do the following: -- List models (`juju models`) -- List machines (`juju machines`) -- Show the status (`juju status`) + - List models (`models`) + - List machines (`machines`) + - Show the status (`status`) + +For write access, the user can use Juju as an operator, beginning with the +following major actions: -For write access, the user can begin with the following major commands: + - Deploy applications (`deploy`) + - Scale out applications (`add-unit`) -- Deploy applications (`juju deploy`) -- Scale out applications (`juju add-unit`) -Further reading: + -- A walkthrough of typical commands is provided in - [Workflow scenarios](./users-workflows.html#basic_setup_and_single_user.html). -- Other write commands are listed on the - [command reference page](./commands.html). -- An explanation of how users gain access to models is provided in - [Users and models](./users-models.html). -- An analysis of the output to certain commands is given in - [Sample commands](./users-sample-commands.html). +[multiuser]: ./multiuser.md From a2a340616fba16f9e27c4f9369bf902cd0710790 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 14:33:36 -0500 Subject: [PATCH 177/311] remove users-creating.md --- src/en/users-creating.md | 48 ---------------------------------------- 1 file changed, 48 deletions(-) delete mode 100644 src/en/users-creating.md diff --git a/src/en/users-creating.md b/src/en/users-creating.md deleted file mode 100644 index 2be1510c0..000000000 --- a/src/en/users-creating.md +++ /dev/null @@ -1,48 +0,0 @@ -Title: Creating Juju users - - - - -# Lost tokens - -If a situation occurs where the registering token fails to work for some -reason, or is lost, a new token can be generated by the admin user with the -`change-user-password` command. For example, to generate a new token for -'jon', the admin user can use this command with the '--reset' switch: - -```bash -juju change-user-password jon --reset -``` - -The previous token will now be invalid, and the user should register with -the new token. - -## Logins and logouts - -On any given client system, each controller that shows up with -`juju controllers` accepts a single login; a logout is necessary before logging -in to the same controller. - -A newly-registered user is automatically logged in to a session. To log out of -the current Juju user session: - -```bash -juju logout -``` - -And to log back in, either on the same client system or not, using the same -user we added earlier: - -```bash -juju login -u jon -``` - -Once a user logs in they become the current user. The following is a quick way -to determine the current user (as well as the current controller and model): - -```bash -juju whoami -``` - -The command `juju show-user` can also be used to get the current user, in -addition to other information on the user. From 6af8b22b1d72ecd96ccb3588e65723ec2b727310 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 21:05:32 -0500 Subject: [PATCH 178/311] continue refactor; drive-by review of models-adding.md --- src/en/models-adding.md | 81 ++++++++++--------------- src/en/multiuser.md | 131 +++++++++++++++++++++++++++++++++++++--- src/en/users-auth.md | 93 +++++++++------------------- src/en/users-manage.md | 30 ++++++--- src/en/users-misc.md | 14 ----- src/en/users-models.md | 123 ++----------------------------------- src/en/users.md | 11 ++-- 7 files changed, 215 insertions(+), 268 deletions(-) diff --git a/src/en/models-adding.md b/src/en/models-adding.md index e1bd2f423..61da11904 100644 --- a/src/en/models-adding.md +++ b/src/en/models-adding.md @@ -1,85 +1,66 @@ Title: Adding a model +TODO: What "appropriate command options"? # Adding a model -A Juju [controller][controller] can host multiple models to accommodate -different workloads or use cases. When a controller is created, it creates -an initial model called 'default', but more models can be added to the -controller using the `juju add-model` command: +A controller can host multiple models to accommodate different workloads or use +cases. When a controller is created, it creates two initial models called +'controller' and 'default', but more models can be added with the `add-model` +command. -``` -juju add-model [options] -``` +A new model inherits, by default, the cloud credentials used to create the +controller and the SSH keys copied across the model will be those of the +controller model. The administrator can override these defaults with the +appropriate command options. Model names can be the same when hosted on different controllers, but they must -be unique when hosted on a single controller. For example, two users could both -have a model called 'secret', but each user could only host one model names -'secret' on a single controller. +be unique when hosted on a single controller. Model names can consist only of +lowercase letters, digits, and hyphens (but cannot start with a hyphen). -Model names may only contain lowercase letters, digits and hyphens, and may not -start with a hyphen. - -See `juju help add-model` for details on this command or see the -[command reference page][commands]. +See section [Managing models in a multi-user context][multiuser-models] for +information on that subject. ## Examples -Add a model named 'lxd-trusty-staging' for the current (LXD) controller: +Add a model named 'lxd-staging' to the current controller: ```bash -juju add-model lxd-trusty-staging +juju add-model lxd-staging ``` -It is possible to add a model for a controller different to the current one, by -specifying the controller to use. To add a model named 'gce-test' for the -non-current 'gce' controller: +It is possible to add a model to a controller different to the current one. To +add a model named 'gce-test' for the non-current 'gce' controller: ```bash -juju add-model gce-test --controller gce +juju add-model gce-test -c gce ``` -Add a model named 'rackspace-prod' for the current (Rackspace) controller, -specifying an existing credential ('mysecret'): +Add a model named 'rackspace-prod' to the current controller, specifying an +existing credential name of 'jon': ```bash -juju add-model rackspace-prod --credential mysecret +juju add-model rackspace-prod --credential jon ``` -By default, Juju will automatically select the newly created model. -Subsequent commands (unless using the `-m` switch to -choose a specific model) will operate on this model. This can be confirmed -by running the `juju switch` command with no arguments. So, for example, -after the above command, running: +By default, Juju will automatically change to the newly created model. +Subsequent commands, unless the `-m` option is used to select a specific model, +will operate on this model. This can be confirmed by running the `switch` +command with no arguments. So, for example, after the above command, running: ```bash juju switch ``` -...will return output like this: +will return output like this: -```bash +```no-highlight rackspace:admin/rackspace-prod ``` -In some cases (e.g. when scripting), this behaviour may be undesirable. In -this case, you can add `--no-switch` to the command to keep the current model -selected: - -```bash -juju add-model rackspace-dev --no-switch -juju switch -``` - -...will still return: - -```bash -rackspace:admin/rackspace-prod -``` - - - +In some cases (e.g. when scripting), this behaviour may be undesirable. In this +case, you can add `--no-switch` option to keep the current model selected. + -[controller]: ./controllers.html -[commands]: ./commands.html#juju-add-model +[multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context diff --git a/src/en/multiuser.md b/src/en/multiuser.md index c0f32d4b9..08dd4f5ee 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -1,4 +1,6 @@ Title: Using Juju with multiple users +TODO: Stuff on user-added models (ssh key and credentials) + Check the functionality of admin user access level. This currently appears to do nothing (not destroy models, nor backups) # Using Juju with multiple users @@ -6,14 +8,38 @@ Juju has an internal user framework that allows for the sharing of controllers and models. To achieve this, a Juju user can be created that is of a certain type; be granted specific permissions; and be authenticated in a certain way. +[Machine SSH authentication][users-auth] + +## Creating users + +There are two ways users are introduced into Juju: + + 1. via the `bootstrap` command, which creates the initial controller + administrator + 1. via the `add-user` command, which creates a generic user + +The second sets up a password but the first is left without one. This is why if +such an admin tries to log out (`logout`) before creating a password the +command will fail and a warning will be displayed. An admin should, therefore, +create a password once the controller is created: + +```bash +juju bootstrap aws +juju change-user-password +``` + +In a Juju context, the term "credential" is related to the accessing of a +chosen backing cloud, and not to Juju users. See [Credentials][credentials] for +further clarification. + [User types][users] -# Creating users +### Creating a generic user -A user is added to a controller by the controller administrator. This process -yields a text string that encodes information about the user and the -controller. This string is supplied to the intended operator who will use it to -*register* the controller using their own Juju client. +When the `add-user` command is used, a string of text is produced that encodes +information about the user and the controller. This string is supplied to the +intended operator who will use it to *register* the controller using their own +Juju client. The user will be asked to enter an arbitrary (but hopefully meaningful) name to the controller as well as create a password for themselves. The controller name @@ -28,8 +54,6 @@ stored on the controller. (i.e. to contact the controller LXD container the client traffic must be routed through the LXD host). -## User creation and controller registration - To create user 'mat' the controller administrator uses the `add-user` command: ```bash @@ -72,8 +96,101 @@ of a model to grant access to that model with "juju grant". The name of the original controller, in this case 'lxd-bionic-1', is offered as a default controller name. +#### Lost registration string + +If a situation occurs where the registering token fails to work for some +reason, or is lost, a new token can be generated by the admin user with the +`change-user-password` command. For example, to generate a new token for 'jon', +the admin user can use this command with the '--reset' switch: + +```bash +juju change-user-password jon --reset +``` + +The previous token will now be invalid, and the user should register with +the new token. + +## Managing models in a multi-user context + +The model creator becomes, by default, the model owner. However, the creation +process does allow for owner designation. To add model 'arena' and designate +user 'tron' as the owner: + +```bash +juju add-model --owner=tron arena +``` + +See the [Adding a model][models-adding] page for the basics on adding models. + +If two users, say 'jane' and 'claire', each have a model with the same name, +'foo', these models can be queried using the notation `{owner}/{model}`, +instead of just the model name. For example, 'claire' can get the status of the +model belonging to 'jane' in this way: + +```bash +juju status -m jane/foo +``` + +### Models and user access + +An administrator can use the `grant` command to give a user 'read', 'write', +or 'admin' access to a model. + + - `read`: A user can view the state of a model (e.g. `models`, `machines`, and + `status`) + - `write`: In addition to 'read' abilities, a user can modify/configure models + (e.g. `model-config` and `model-defaults`). + - `admin`: In addition to 'write' abilities, a user can perform model upgrades + (`upgrade-model`) and connect to machines via `juju ssh`. Makes the user an + effective model owner. + +Here we give 'bob' write access to model 'genesis': + +```bash +juju grant bob write genesis +``` + +See [Users][regularusers] for details on available commands. + +### Controller access + +A controller actually refers to a special kind of model that acts as the +nucleus for each cloud environment. Properly managed access to any controller +is critical to the security and stability of all its workload models. + +In addition to the two levels of user access for models, three further levels +of access are used to manage access to a controller: + + - `login`: the standard access level for any user, enabling them to log in to + a controller. + - `add-model`: in addition to login access, a user is also be permitted to add + and remove models. + - `superuser`: makes a user an effective controller administrator. + +The command syntax for controller access is the same as for model access, only +without the need to specify a model. As usual, with no controller specified via +the `-c` option, the current controller will be assumed the target. + +Here we give 'jim' the 'add-model' permission: + +```bash +juju grant jim add-model +``` + +The `users` command can be used to list all users registered to a controller, +along with their access levels. The output will look similar to the following: + +```no-highlight +Controller: admin-lxd + +Name Display name Access Date created Last connection +admin* admin superuser 2016-11-14 just now +bob login 1 hour ago 58 minutes ago +jim add-model 2016-11-14 58 minutes ago +``` [users]: ./users.md +[users-auth]: ./users-auth.md diff --git a/src/en/users-auth.md b/src/en/users-auth.md index 630e738c2..c13c05345 100644 --- a/src/en/users-auth.md +++ b/src/en/users-auth.md @@ -1,40 +1,10 @@ -Title: Users and authentication +Title: Machine SSH authentication TODO: Stuff on user-created models (ssh key and credentials) +# Machine SSH authentication -# Users and authentication - -This section deals with topics related to user authentication and general user -security. - - -## Users and passwords - -There are two ways users are introduced into Juju: the initial administrator of -a controller via the controller creation step and a non-administrator via the -user registration step. The latter sets up the user's Juju password but the -former is left without an actual password. This is why if such a user tries to -log out (`juju logout`) before creating a password the command will fail and a -warning will be displayed. An administrator should, therefore, create a -password once the controller is created. They must do so if multiple Juju users -will be using the same system user account: - -```bash -juju bootstrap aws mycontroller -juju change-user-password -``` - -See [Creating a controller][controllers-creating] for details on controller -creation. - -## Credentials - -Credentials managed in Juju are related to the accessing of the chosen -cloud-backed resource. They are not related to Juju users themselves in any -way. Credentials added to Juju remain local to the system user (on Ubuntu: -`~/.local/share/juju/credentials.yaml`). - -See [Credentials][credentials] for more on this topic. +This page explains how SSH authentication works when contacting a Juju +machine. ## SSH access @@ -43,14 +13,14 @@ to a model then that key is placed on all machines (present and future) in that model. Each Juju machine provides a user account named 'ubuntu' and it is to this -account that public keys are added when using the Juju SSH commands ( -`juju add-ssh-key` and `juju import-ssh-key`). Because this user is effectively -the 'root' user (passwordless sudo privileges), the granting of SSH access must -be done with due consideration. +account that public keys are added when using the Juju SSH commands +(`add-ssh-key` and `import-ssh-key`). Because this user is effectively the +'root' user (passwordless sudo privileges), the granting of SSH access must be +done with due consideration. It is possible to connect to a Juju machine in one of two ways: -- Via Juju, using the `juju ssh` command +- Via Juju, using `juju ssh` - Direct access, using a standard SSH client (e.g `PuTTY` on Windows or `ssh` [OpenSSH] on Linux) @@ -59,16 +29,15 @@ Connecting via Juju involves a second degree of security, as explained below. Regardless of the method used to connect, a public SSH key must be added to the model. In the case of direct access, it remains possible for a key to be added to an individual machine using standard methods (manually copying a key to the -`authorized_keys` file or by way of a command such as `ssh-import-id` for -Debian-based Linux distributions such as Ubuntu). +`authorized_keys` file or by way of a command such as `ssh-import-id` in the +case of Ubuntu). ### Juju ssh -When using the `juju ssh` command, Juju's own user rights system imposes an +When using the Juju `ssh` command, Juju's own user rights system imposes an extra degree of security by permitting access solely from a Juju user, and only one with sufficient permissions. How this works depends on whether the user is -an admin or a non-admin. See [Juju users][users] for a breakdown of the -different user types. +an admin or a non-admin (see [User types][users]). For example, to connect to a machine with an id of '0': @@ -82,28 +51,27 @@ allocation"). #### Admin user -When a controller is created (see -[Creating a controller][controllers-creating]) a passphraseless SSH keypair -will be generated and placed under `~/.local/share/juju/ssh`. The public key -(`juju_id_rsa.pub`) will be installed in the 'ubuntu' account on every machine -created within every model belonging to this controller. During creation, if -there is an existing public key named `~/.ssh/id_rsa.pub` then it will also be -placed on every machine. +When a controller is created a passphraseless SSH keypair will be generated and +placed under `~/.local/share/juju/ssh`. The public key (`juju_id_rsa.pub`) will +be installed in the 'ubuntu' account on every machine created within every +model belonging to this controller. During creation, if there is an existing +public key named `~/.ssh/id_rsa.pub` then it will also be placed on every +machine. As long as the controller administrator has access to either of the above keys -he/she can connect to any machine with the `juju ssh` command. +he/she can connect to any machine with `juju ssh`. #### Regular user In order for a regular Juju user to connect with `juju ssh` the user must: -- be created (`juju add-user`) -- be registered (`juju register`) -- be logged in (`juju login`) -- have 'admin' rights to the model (`juju grant`) -- have their public key added to the model by an admin (`juju add-ssh-key` or - `juju import-ssh-key`) -- be in possession of the corresponding private key + - be created (`add-user`) + - have registered a controller (`register`) + - be logged in (`login`) + - have 'admin' rights to the model (`grant`) + - have their public SSH key added to the model by an admin (`add-ssh-key` or + `import-ssh-key`) + - be in possession of the corresponding private SSH key See [Users and models][models-users] for information on managing user permissions. @@ -137,8 +105,5 @@ ssh ubuntu@10.149.29.143 -[controllers-creating]: ./controllers-creating.html -[credentials]: ./credentials.html -[users]: ./users.html -[models]: ./models.html -[models-users]: ./users-models.html +[users]: ./users.md +[models-users]: ./users-models.md diff --git a/src/en/users-manage.md b/src/en/users-manage.md index 4cd06efa3..5c5a038b3 100644 --- a/src/en/users-manage.md +++ b/src/en/users-manage.md @@ -7,11 +7,25 @@ This section covers topics related to managing users at the administrative level. +## Viewing user model access + +```bash +juju models --user mat +``` + +```no-highlight +Controller: lxd-bionic-1 + +Model Cloud/Region Status Access Last connection +admin/euphoric* localhost/localhost available read never connected +``` + ## Disabling and re-enabling users -An administrator can sever user communication from a user to the controller -they manage by disabling them. The effect is immediate. To get a list of -potential users to disable the `juju users` command can first be used. +To immediately sever a user's communication with their controller the +`disable-user` command is employed. To re-establish communication the +`enable-user` command is used. To get a list of potential users to disable the +`users` command can first be used. Examples: @@ -27,17 +41,14 @@ To re-enable the user 'mike': juju enable-user mike ``` -Disabled users do not show up in the output to `juju users` unless the -'--all' option is used: - - - +Disabled users are suppressed in the output to the `users` command unless the +`--all` option is used, whereby the output will show "disabled": ```no-highlight Controller: cstack Name Display name Access Date created Last connection -admin* admin superuser 2016-10-12 just now +admin* admin superuser 2018-12-12 just now mike login 17 minutes ago never connected (disabled) ``` @@ -59,4 +70,3 @@ juju change-user-password mike ``` Then simply follow the prompts to enter and confirm a new password. - diff --git a/src/en/users-misc.md b/src/en/users-misc.md index 2be1510c0..6b2660cd7 100644 --- a/src/en/users-misc.md +++ b/src/en/users-misc.md @@ -3,20 +3,6 @@ Title: Creating Juju users -# Lost tokens - -If a situation occurs where the registering token fails to work for some -reason, or is lost, a new token can be generated by the admin user with the -`change-user-password` command. For example, to generate a new token for -'jon', the admin user can use this command with the '--reset' switch: - -```bash -juju change-user-password jon --reset -``` - -The previous token will now be invalid, and the user should register with -the new token. - ## Logins and logouts On any given client system, each controller that shows up with diff --git a/src/en/users-models.md b/src/en/users-models.md index b11c27da0..a21942bad 100644 --- a/src/en/users-models.md +++ b/src/en/users-models.md @@ -1,118 +1,4 @@ -Title: Juju users and models -TODO: Stuff on user-added models (ssh key and credentials) - Check the functionality of admin user access level. This currently - appears to do nothing (not destroy models, nor backups) -# Users and models - -This section is about understanding models with multiple users. - -## Adding models - -When an administrator adds a model, by default, the cloud credentials used -throughout the model will be those that the admin used to create the controller -and the SSH keys copied across the model will be those of the controller model. -The administrator can override these defaults with the appropriate command -options. - -The model creator becomes, by default, the model owner. However, the creation -process does allow for owner designation. - -Examples: - -Add model 'mymodel' (in the current controller): - -```bash -juju add-model mymodel -``` - -Add model 'mymodel' and designate user 'tron' as the owner: - -```bash -juju add-model --owner=tron mymodel -``` - -See [Adding a model][addmodel] for details on adding models. - - -## Models and user access - -An administrator can use the `grant` command to grant a user 'read', 'write', -or 'admin' access to any model. - -- `read`: A user can view the state of a model with the `models`, - `machines` and `status` commands. -- `write`: In addition to 'read' abilities, a user can modify/configure models. -- `admin`: In addition to 'write' abilities, a user can backup models and - connect to machines via the `juju ssh` command. - -To give 'bob' read-only access to the model 'mymodel', for example, the -administrator would enter the following: - -```bash -juju grant bob read mymodel -``` - -To give 'jim' write access to the same model, the administrator would use the -following: - -```bash -juju grant jim write mymodel -``` -See [Users][regularusers] for details on available commands. - -!!! Note: - Each user has control over naming the models they own. This means it is - possible for two users, `jane` and `claire`, to each have a model with the same - name, `foo`. This could cause difficulty when `claire` needs to access `jane`'s - model. Because of this, it is possible to refer to models using - `{owner}/{model}` in place of just the model name. For example, `claire` can - get the status of the model using `juju status -m jane/foo`. - -## Controller access - -A controller is a special kind of model that acts as the management node for -each cloud environment. Properly managed access to any controller is critical -to the security and stability of your cloud and all its models. - -In addition to the two levels of user access for models, three further levels -of access are used to manage access to Juju's controllers: - -- `login`: the standard access level for any user, enabling them - to connect to a cloud and access any permitted models. -- `add-model`: in addition to login access, a user is also be permitted - to add and remove new models. -- `superuser`: grants a user the same permissions as an administrator and complete - control over the deployed environment. - -The `grant` syntax for controller access is the same as model -access, only without the need to specify a model. With no controller specified, -the current controller will be assumed the target: - -```bash -juju grant jim add-model -``` - -A controller can be specified using the `--controller` argument followed by the -name of the controller: - -```bash -juju grant jim add-model --controller admin-lxd -``` - -The `users` command can be used to list all users registered to a controller, along -with their access levels. The output will look similar to the following: - - - -```no-highlight -Controller: admin-lxd - -Name Display name Access Date created Last connection -admin* admin superuser 2016-11-14 just now -bob login 1 hour ago 58 minutes ago -jim add-model 2016-11-14 58 minutes ago -``` ### Controller access for external users @@ -167,7 +53,7 @@ by this user will use these credentials. juju add-model test --credential gce ``` -To learn more about credentials, see [credentials]. +To learn more about credentials, see [Credentials][credentials]. ## Public controllers @@ -214,9 +100,10 @@ juju revoke bob read mymodel add-credential'. -[addmodel]: ./models-adding.html -[credentials]: ./credentials.html + + +[models-adding]: ./models-adding.md +[credentials]: ./credentials.md [regularusers]: ./users.html#regular-users [jaas]: https://jujucharms.com/jaas [sso]: https://login.ubuntu.com/ - diff --git a/src/en/users.md b/src/en/users.md index 0445e21b1..6dc7f8cbb 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -20,8 +20,9 @@ creator and any user the creator/initial_admin has granted write access to the 'controller' model. There is no overarching "Juju administrator" since multiple controllers, and therefore multiple administrators, are possible. -A *model owner* is the model creator or a user who has been designated as such -during the model creation process. +A *model owner* is the model creator; a user who has been designated as such +during model creation; or a user who has been granted the 'admin' permissions +to the model. A *regular user* is one who is neither an administrator nor a model owner. Such a user requires access to a model in order to do anything at the Juju level. @@ -83,7 +84,7 @@ actions (in the context of their controller): - Revoke user access from models (`revoke`) - Remove models (`destroy-model`) - Remove the controller (`destroy-controller` or `kill-controller`) - - Upgrade any model (`upgrade-model`) + - Upgrade models (`upgrade-model`) - Manage controller backups (e.g. `create-backup`) ### Model owners @@ -93,8 +94,8 @@ A model owner has the power to list users who have access to the model they own ### Regular users -The ability of a regular user depends on the model access rights (read-only or -write) they have been granted. +The ability of a regular user depends on the model access rights ('read' or +'write') they have been granted. For read-only access, the user can do the following: From 7af75b29c40b37b4cfc1074c9f08afd53233bd6e Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 22:24:27 -0500 Subject: [PATCH 179/311] ongoing --- src/en/multiuser.md | 154 +++++++++++++++++++++++++++++++---------- src/en/users-auth.md | 4 +- src/en/users-manage.md | 72 ------------------- src/en/users.md | 9 ++- 4 files changed, 124 insertions(+), 115 deletions(-) diff --git a/src/en/multiuser.md b/src/en/multiuser.md index 08dd4f5ee..dbf822685 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -96,22 +96,74 @@ of a model to grant access to that model with "juju grant". The name of the original controller, in this case 'lxd-bionic-1', is offered as a default controller name. -#### Lost registration string +## Disabling and re-enabling users -If a situation occurs where the registering token fails to work for some -reason, or is lost, a new token can be generated by the admin user with the -`change-user-password` command. For example, to generate a new token for 'jon', -the admin user can use this command with the '--reset' switch: +To immediately sever a user's communication with their controller the +`disable-user` command is employed. To re-establish communication the +`enable-user` command is used. + +To disable the user 'mike': + +```bash +juju disable-user mike +``` + +To re-enable: + +```bash +juju enable-user mike +``` + +Disabled users are suppressed in the output to the `users` command unless the +`--all` option is used, whereby the output will show "disabled": + +```no-highlight +Controller: cstack + +Name Display name Access Date created Last connection +admin* admin superuser 2018-12-12 just now +mike login 17 minutes ago never connected (disabled) +``` + +## Changing user passwords + +A user is prompted to set a password when registering a controller. This +password can subsequently be changed either by the user himself or by the +controller admin. For the user, it is simply a matter of running: + +```bash +juju change-user-password +``` + +The admin user supplies the name of the user whose password is to be changed: + +```bash +juju change-user-password mike +``` + +Then simply follow the prompts to enter and confirm a new password. + +## Re-generating a lost registration string + +If the original registering token fails to work or is lost a new token can be +generated by the controller admin. This is done through the use of the +`--reset` option in conjunction with the `change-user-password` command. For +example, to generate a new token for 'jon': ```bash juju change-user-password jon --reset ``` -The previous token will now be invalid, and the user should register with -the new token. +The previous token will be invalidated, and the user should register with the +new token. ## Managing models in a multi-user context +In this section we go over the various ways models can be managed in a +multi-user context. + +### Providing model ownership during model creation + The model creator becomes, by default, the model owner. However, the creation process does allow for owner designation. To add model 'arena' and designate user 'tron' as the owner: @@ -122,19 +174,10 @@ juju add-model --owner=tron arena See the [Adding a model][models-adding] page for the basics on adding models. -If two users, say 'jane' and 'claire', each have a model with the same name, -'foo', these models can be queried using the notation `{owner}/{model}`, -instead of just the model name. For example, 'claire' can get the status of the -model belonging to 'jane' in this way: - -```bash -juju status -m jane/foo -``` - -### Models and user access +### Models access -An administrator can use the `grant` command to give a user 'read', 'write', -or 'admin' access to a model. +A controller admin uses the `grant` command to give a user 'read', 'write', or +'admin' access to a model: - `read`: A user can view the state of a model (e.g. `models`, `machines`, and `status`) @@ -142,7 +185,8 @@ or 'admin' access to a model. (e.g. `model-config` and `model-defaults`). - `admin`: In addition to 'write' abilities, a user can perform model upgrades (`upgrade-model`) and connect to machines via `juju ssh`. Makes the user an - effective model owner. + effective model owner. See [Model owners][users-owners] for commands + available to such a user. Here we give 'bob' write access to model 'genesis': @@ -150,22 +194,58 @@ Here we give 'bob' write access to model 'genesis': juju grant bob write genesis ``` -See [Users][regularusers] for details on available commands. +Current model access for a user can be viewed by specifying the user with the +`models` command. Here we inspect the access enjoyed by user 'mat': + +```bash +juju models --user mat +``` + +Sample output: + +```no-highlight +Controller: lxd-bionic-1 + +Model Cloud/Region Status Access Last connection +admin/euphoric* localhost/localhost available read never connected +``` + +Access can be viewed on a per-model basis by using the `show-model` command. +Here we query model 'mara': + +```bash +juju show-model mara +``` + +Partial output: + +```no-highlight + users: + admin: + display-name: admin + access: admin + last-connection: never connected + jim: + access: write + last-connection: never connected + pete: + access: admin + last-connection: never connected +``` ### Controller access A controller actually refers to a special kind of model that acts as the -nucleus for each cloud environment. Properly managed access to any controller -is critical to the security and stability of all its workload models. - -In addition to the two levels of user access for models, three further levels -of access are used to manage access to a controller: +nucleus for each cloud environment. In addition to the three levels of model +access, three further levels of access are available for managing access to a +controller: - - `login`: the standard access level for any user, enabling them to log in to - a controller. - - `add-model`: in addition to login access, a user is also be permitted to add - and remove models. - - `superuser`: makes a user an effective controller administrator. + - `login`: the standard access level, enabling a user to log in to a + controller. + - `add-model`: in addition to login access, a user can add and remove models. + - `superuser`: makes a user an effective controller administrator. See + [Controller administrators][users-admins] for commands available to such a + user. The command syntax for controller access is the same as for model access, only without the need to specify a model. As usual, with no controller specified via @@ -177,16 +257,16 @@ Here we give 'jim' the 'add-model' permission: juju grant jim add-model ``` -The `users` command can be used to list all users registered to a controller, -along with their access levels. The output will look similar to the following: +Current controller access for all users registered to the controller can be +viewed with the `users` command: ```no-highlight Controller: admin-lxd Name Display name Access Date created Last connection -admin* admin superuser 2016-11-14 just now -bob login 1 hour ago 58 minutes ago -jim add-model 2016-11-14 58 minutes ago +admin* admin superuser 2018-12-14 just now +bob login 1 hour ago 50 minutes ago +jim add-model 2018-12-14 58 minutes ago ``` @@ -194,3 +274,5 @@ jim add-model 2016-11-14 58 minutes ago [users]: ./users.md [users-auth]: ./users-auth.md +[users-owners]: ./users.md#model-owners +[users-admins]: ./users.md#controller-administrators diff --git a/src/en/users-auth.md b/src/en/users-auth.md index c13c05345..5d9cfac9a 100644 --- a/src/en/users-auth.md +++ b/src/en/users-auth.md @@ -73,7 +73,7 @@ In order for a regular Juju user to connect with `juju ssh` the user must: `import-ssh-key`) - be in possession of the corresponding private SSH key -See [Users and models][models-users] for information on managing user +See [Models access][multiuser-models-access] for information on managing user permissions. In terms of the private key, the easiest way to ensure it is used is to have it @@ -106,4 +106,4 @@ ssh ubuntu@10.149.29.143 [users]: ./users.md -[models-users]: ./users-models.md +[multiuser-models-access]: ./multiuser.md#models-access diff --git a/src/en/users-manage.md b/src/en/users-manage.md index 5c5a038b3..e69de29bb 100644 --- a/src/en/users-manage.md +++ b/src/en/users-manage.md @@ -1,72 +0,0 @@ -Title: Juju user management - - -# User management - -This section covers topics related to managing users at the administrative -level. - - -## Viewing user model access - -```bash -juju models --user mat -``` - -```no-highlight -Controller: lxd-bionic-1 - -Model Cloud/Region Status Access Last connection -admin/euphoric* localhost/localhost available read never connected -``` - -## Disabling and re-enabling users - -To immediately sever a user's communication with their controller the -`disable-user` command is employed. To re-establish communication the -`enable-user` command is used. To get a list of potential users to disable the -`users` command can first be used. - -Examples: - -To disable the user 'mike': - -```bash -juju disable-user mike -``` - -To re-enable the user 'mike': - -```bash -juju enable-user mike -``` - -Disabled users are suppressed in the output to the `users` command unless the -`--all` option is used, whereby the output will show "disabled": - -```no-highlight -Controller: cstack - -Name Display name Access Date created Last connection -admin* admin superuser 2018-12-12 just now -mike login 17 minutes ago never connected (disabled) -``` - -## Changing user passwords - -The local user is prompted to set a password when registering the controller. -This password can subsequently be changed either by the user or by the admin -user of the controller. For the user, it is simply a matter of running: - -```bash -juju change-user-password -``` - -The admin user must also supply the name of the user account whose password -is to be changed: - -```bash -juju change-user-password mike -``` - -Then simply follow the prompts to enter and confirm a new password. diff --git a/src/en/users.md b/src/en/users.md index 6dc7f8cbb..32daafc0f 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -14,11 +14,10 @@ Juju users are not related in any way to the localhost system users; they are purely Juju constructs. A *controller administrator* is a user who has access to the controller model. -This Juju user is called 'admin' and is set up as part of the controller -creation step. Practically, this set of users is comprised of the controller -creator and any user the creator/initial_admin has granted write access to the -'controller' model. There is no overarching "Juju administrator" since multiple -controllers, and therefore multiple administrators, are possible. +This set of users is comprised of the controller creator and any user the +creator/initial_admin has granted 'superuser' access to the 'controller' model. +There is no overarching "Juju administrator" since multiple controllers, and +therefore multiple administrators, are possible. A *model owner* is the model creator; a user who has been designated as such during model creation; or a user who has been granted the 'admin' permissions From 4db36f1f78bf2749e736e4fc4bd2eb81e1345d1d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 22:24:40 -0500 Subject: [PATCH 180/311] remove users-manage.md --- src/en/users-manage.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 src/en/users-manage.md diff --git a/src/en/users-manage.md b/src/en/users-manage.md deleted file mode 100644 index e69de29bb..000000000 From 115f2fa00c8a3456a2f6d98b9f589b1230b84059 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 23:00:04 -0500 Subject: [PATCH 181/311] ongoing --- src/en/multiuser.md | 36 ++++++++++++++++++++++++++++++++++++ src/en/users-misc.md | 34 ---------------------------------- 2 files changed, 36 insertions(+), 34 deletions(-) diff --git a/src/en/multiuser.md b/src/en/multiuser.md index dbf822685..abb37a5f3 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -96,6 +96,39 @@ of a model to grant access to that model with "juju grant". The name of the original controller, in this case 'lxd-bionic-1', is offered as a default controller name. +## Logins and logouts + +A user who has just registered a controller is automatically logged in to that +controller. + +A user can log out at any time: + +```bash +juju logout +``` + +To log in to a controller, the operator needs to specify both the user and the +controller: + +```bash +juju login -u mat -c lxd-bionic-1 +``` + +The following is a quick way to determine the current user (as well as the +current controller and model): + +```bash +juju whoami +``` + +Example output: + +```no-highlight +Controller: lxd-bionic-1 +Model: +User: mat +``` + ## Disabling and re-enabling users To immediately sever a user's communication with their controller the @@ -269,6 +302,9 @@ bob login 1 hour ago 50 minutes ago jim add-model 2018-12-14 58 minutes ago ``` +The `show-user` command can also be used to get controller access on a per-user +basis, in addition to other information on the user. + diff --git a/src/en/users-misc.md b/src/en/users-misc.md index 6b2660cd7..e69de29bb 100644 --- a/src/en/users-misc.md +++ b/src/en/users-misc.md @@ -1,34 +0,0 @@ -Title: Creating Juju users - - - - -## Logins and logouts - -On any given client system, each controller that shows up with -`juju controllers` accepts a single login; a logout is necessary before logging -in to the same controller. - -A newly-registered user is automatically logged in to a session. To log out of -the current Juju user session: - -```bash -juju logout -``` - -And to log back in, either on the same client system or not, using the same -user we added earlier: - -```bash -juju login -u jon -``` - -Once a user logs in they become the current user. The following is a quick way -to determine the current user (as well as the current controller and model): - -```bash -juju whoami -``` - -The command `juju show-user` can also be used to get the current user, in -addition to other information on the user. From 37391f4c1afce79f8ede2f3027382b9bef717dd7 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 12 Dec 2018 23:00:18 -0500 Subject: [PATCH 182/311] remove users-misc.md --- src/en/users-misc.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 src/en/users-misc.md diff --git a/src/en/users-misc.md b/src/en/users-misc.md deleted file mode 100644 index e69de29bb..000000000 From 40f0ef4e771367edf19feddd04a22d32f8e9b6bd Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 13 Dec 2018 14:22:52 -0500 Subject: [PATCH 183/311] finish first major pass; remove users-models.md --- src/en/metadata.yaml | 4 +- src/en/multiuser.md | 71 +++++++++++++++++++-------- src/en/users-models.md | 109 ----------------------------------------- src/en/users.md | 39 ++++++++------- 4 files changed, 73 insertions(+), 150 deletions(-) delete mode 100644 src/en/users-models.md diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 05c0a987a..8796d5040 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -43,8 +43,8 @@ navigation: location: controllers-ha.md - title: Application high availability location: charms-ha.md - - title: Understanding users - location: users.md + - title: Working with multiple users + location: multiuser.md - title: Troubleshooting location: troubleshooting.md - title: Juju logs diff --git a/src/en/multiuser.md b/src/en/multiuser.md index abb37a5f3..f2ce7f211 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -1,8 +1,8 @@ -Title: Using Juju with multiple users +Title: Working with multiple users TODO: Stuff on user-added models (ssh key and credentials) Check the functionality of admin user access level. This currently appears to do nothing (not destroy models, nor backups) -# Using Juju with multiple users +# Working with multiple users Juju has an internal user framework that allows for the sharing of controllers and models. To achieve this, a Juju user can be created that is of a certain @@ -14,9 +14,9 @@ type; be granted specific permissions; and be authenticated in a certain way. There are two ways users are introduced into Juju: - 1. via the `bootstrap` command, which creates the initial controller + 1. with the `bootstrap` command, which creates the initial controller administrator - 1. via the `add-user` command, which creates a generic user + 1. with the `add-user` command, which creates a generic user The second sets up a password but the first is left without one. This is why if such an admin tries to log out (`logout`) before creating a password the @@ -33,6 +33,7 @@ chosen backing cloud, and not to Juju users. See [Credentials][credentials] for further clarification. [User types][users] +[External users][users-external] ### Creating a generic user @@ -46,7 +47,7 @@ the controller as well as create a password for themselves. The controller name needs to be unique within the context of the client. The user's password is stored on the controller. -!!! Note: +!!! Important: Controller registration (and any other Juju operations that involves communication between a client and a controller) necessitates the client be able to contact the controller over the network on TCP port 17070. In @@ -54,7 +55,7 @@ stored on the controller. (i.e. to contact the controller LXD container the client traffic must be routed through the LXD host). -To create user 'mat' the controller administrator uses the `add-user` command: +To create user 'mat' a controller administrator uses the `add-user` command: ```bash juju add-user mat @@ -70,7 +71,7 @@ Please send this command to mat: "mat" has not been granted access to any models. You can use "juju grant" to grant access. ``` -The administrator provides the command (manually) to the intended operator, who +An administrator provides the command (manually) to the intended operator, who will execute it: ```bash @@ -161,7 +162,7 @@ mike login 17 minutes ago never connected (disabled) ## Changing user passwords A user is prompted to set a password when registering a controller. This -password can subsequently be changed either by the user himself or by the +password can subsequently be changed either by the user himself or by a controller admin. For the user, it is simply a matter of running: ```bash @@ -179,9 +180,9 @@ Then simply follow the prompts to enter and confirm a new password. ## Re-generating a lost registration string If the original registering token fails to work or is lost a new token can be -generated by the controller admin. This is done through the use of the -`--reset` option in conjunction with the `change-user-password` command. For -example, to generate a new token for 'jon': +generated by a controller admin. This is done through the use of the `--reset` +option in conjunction with the `change-user-password` command. For example, to +generate a new token for 'jon': ```bash juju change-user-password jon --reset @@ -207,7 +208,7 @@ juju add-model --owner=tron arena See the [Adding a model][models-adding] page for the basics on adding models. -### Models access +### Model access A controller admin uses the `grant` command to give a user 'read', 'write', or 'admin' access to a model: @@ -270,8 +271,7 @@ Partial output: A controller actually refers to a special kind of model that acts as the nucleus for each cloud environment. In addition to the three levels of model -access, three further levels of access are available for managing access to a -controller: +access, three further levels of access can be applied to a controller: - `login`: the standard access level, enabling a user to log in to a controller. @@ -282,7 +282,7 @@ controller: The command syntax for controller access is the same as for model access, only without the need to specify a model. As usual, with no controller specified via -the `-c` option, the current controller will be assumed the target. +the `-c` option, the current controller is the assumed target. Here we give 'jim' the 'add-model' permission: @@ -290,11 +290,11 @@ Here we give 'jim' the 'add-model' permission: juju grant jim add-model ``` -Current controller access for all users registered to the controller can be -viewed with the `users` command: +Current controller access for all users registered to a controller can be +viewed with the `users` command. Example output: ```no-highlight -Controller: admin-lxd +Controller: azure-1 Name Display name Access Date created Last connection admin* admin superuser 2018-12-14 just now @@ -302,8 +302,38 @@ bob login 1 hour ago 50 minutes ago jim add-model 2018-12-14 58 minutes ago ``` -The `show-user` command can also be used to get controller access on a per-user -basis, in addition to other information on the user. +In addition, a controller admin can use the `show-user` command to get +controller access on a per-user basis, in addition to other information on the +user. + +## Revoking access + +The `revoke` command is used by a controller administrator to demote a user's +access to the next lowest level. That is, if a user has 'write' access to a +model and 'read' is revoked then both 'read' and 'write' are removed. This +works similarly for controller access. If a user has 'superuser' access and +'add-model' is revoked then both 'add-model' and 'superuser' are removed. + +If user 'bob' has 'write' access to model 'gotcha', use the following to remove +all access to this model: + +```bash +juju revoke bob read gotcha +``` + +Confirm this action with `juju models --user bob`. + +If user 'jim' has 'superuser' access to controller 'waves', use the following +to leave the user with just 'login' access: + +```bash +juju revoke -c waves jim add-model +``` + +Confirm this action with `juju show-user --user jim`. + +As usual, if a controller is not specified (`-c`) the default controller is the +currently active one. @@ -312,3 +342,4 @@ basis, in addition to other information on the user. [users-auth]: ./users-auth.md [users-owners]: ./users.md#model-owners [users-admins]: ./users.md#controller-administrators +[credentials]: ./credentials.md diff --git a/src/en/users-models.md b/src/en/users-models.md deleted file mode 100644 index a21942bad..000000000 --- a/src/en/users-models.md +++ /dev/null @@ -1,109 +0,0 @@ - - -### Controller access for external users - -It is possible to give a user access to a controller without creating a local -account for them. Linking the controller to the external identity manager, such -as the Ubuntu SSO, in this way provides the benefit of convenience, as the -authentication system used may also be used for other systems. This reduces -the number of login credentials that users must remember across multiple systems. - -To do this, these criteria must first be met: - -- The user must already have an account on an external identity manager -- The controller must have been created (bootstrapped) using the identity - configuration option, like here where we use the URL for the Ubuntu SSO - and Juju: `--config identity-url=https://api.jujucharms.com/identity` -- The user must first log in to http://jujucharms.com at least once before - attempting to log in to Juju as an external user -- The user must install Juju on the machine from which they will access the - controller - -On the controller, you grant Frances access to add models using: - -```bash -juju grant frances@external addmodel -``` - -!!! Note: - The '@external' is required as it indicates where the credential - comes from, as opposed to '@local'. - -You can allow anyone with an Ubuntu SSO account to create models on this -controller like this: - -```bash -juju grant everyone@external addmodel -``` - -Sharing controller information must be done directly between the controller -owner and the external user, such as via email, and manually adding the -controller information to the local user's `$HOME/.local/share/juju/controllers.yaml` -in Ubuntu and other Linux distributions and the similar location in other OSes. - -The external user will log in from their machine with `juju login -u `. -They will be directed to the URL for the external identity provider so that -they may log in there and then will be granted access to the controller. - -For the external user to create models from the controller, they must have -credentials for that provider, for example, GCE or AWS. Any models created -by this user will use these credentials. - -```bash -juju add-model test --credential gce -``` - -To learn more about credentials, see [Credentials][credentials]. - -## Public controllers - -The `juju login` command can also be used to access a public controller, using -either the name or the host name of the controller as a parameter: - -```bash -juju login jaas -``` - -The above command will add the 'jaas' public controller to the list of -controllers you can use, caching its details in the locally stored -`controllers.yaml` file. - -Public controllers will normally use an external identity provider. -[JAAS][jaas], as used above, uses [Ubuntu SSO][sso], which means you should -register with [https://jujucharms.com/login](https://jujucharms.com/login). - -## Revoke access rights - -The 'revoke' command is used to remove a user's access to either a model or a -controller. To revoke 'add-model' controller access for user 'jim', you would -use the following: - -```bash -juju revoke jim add-model -``` - -After a `revoke` command has been issued, a user's access will reduce to the -next lower access level. With the above example, user 'jim' would have have -'add-model' access reduced to 'login' access on the controller. This also means -that if a user has write access to a model, the following command would revoke -both read and write access: - -```bash -juju revoke bob read mymodel -``` - -!!! Note: - The admin user has credentials stored in the controller and will be able to - perform functions on any model. However, a regular user who has been given - 'add-model' permissions may need to specify which credential to use when - logging in to a model for the first time. To specify a credential, run 'juju - add-credential'. - - - - -[models-adding]: ./models-adding.md -[credentials]: ./credentials.md -[regularusers]: ./users.html#regular-users -[jaas]: https://jujucharms.com/jaas -[sso]: https://login.ubuntu.com/ diff --git a/src/en/users.md b/src/en/users.md index 32daafc0f..b7898bed9 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -2,32 +2,33 @@ Title: User types # User types -*This is in connection with the [Using Juju with multiple users][multiuser] -page. See that resource for background information.* +*This is in connection with the [Working with multiple users][multiuser] page. +See that resource for background information.* There are three kinds of Juju users: controller administrators, model owners, -and regular users. Each user, no matter the kind, is associated with a -controller. In particular, the namespace for users are controller-centric; -names can be duplicated across controllers. +and regular users. Each user, no matter the kind, is associated with one, and +only one, controller. -Juju users are not related in any way to the localhost system users; they are +Juju users are not related in any way to the client system users; they are purely Juju constructs. -A *controller administrator* is a user who has access to the controller model. -This set of users is comprised of the controller creator and any user the -creator/initial_admin has granted 'superuser' access to the 'controller' model. +A *controller administrator* is a user who has full access to the 'controller' +model. This set of users is comprised of the controller creator and any user +the latter user has granted 'superuser' access to the 'controller' model. There is no overarching "Juju administrator" since multiple controllers, and -therefore multiple administrators, are possible. +therefore multiple controller administrators, are possible. Nevertheless, this +user is usually what people refer to as "the admin". -A *model owner* is the model creator; a user who has been designated as such -during model creation; or a user who has been granted the 'admin' permissions +A *model owner* is a user who has full access to a model. This set of users is +comprised of the model creator and any user who has been granted 'admin' access to the model. -A *regular user* is one who is neither an administrator nor a model owner. Such -a user requires access to a model in order to do anything at the Juju level. -Note that although deemed "regular", such a user is far from ordinary since -they can marshal the vast resources of the backing cloud and deploy complex -applications. +A *regular user* is one who is neither a controller administrator nor a model +owner. Such a user requires access to a model in order to do anything at the +Juju level. + +The *operator* is a term used to refer to the actual person who is driving the +Juju client. ## User abilities @@ -88,8 +89,8 @@ actions (in the context of their controller): ### Model owners -A model owner has the power to list users who have access to the model they own -(`users`) as well as upgrade their model (`upgrade-model`). +A model owner can list users who have access to the model (`users`), destroy +the model (`destroy-model`), and upgrade the model (`upgrade-model`). ### Regular users From dce38561a9a650d2a3529a02f3350110c546d390 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 13 Dec 2018 16:56:40 -0500 Subject: [PATCH 184/311] final draft --- src/en/getting-started.md | 1 - src/en/{users-auth.md => machine-auth.md} | 31 ++++++++--------- src/en/metadata.yaml | 2 ++ src/en/models-adding.md | 25 +++++++++----- src/en/models.md | 2 +- src/en/multiuser.md | 42 +++++++++++++---------- src/en/users.md | 30 +++++++--------- 7 files changed, 69 insertions(+), 64 deletions(-) rename src/en/{users-auth.md => machine-auth.md} (84%) diff --git a/src/en/getting-started.md b/src/en/getting-started.md index 61e3628e7..acc32cf2f 100644 --- a/src/en/getting-started.md +++ b/src/en/getting-started.md @@ -314,7 +314,6 @@ some of the following pages of documentation: [jaaslogin]: https://jujucharms.com/login "JAAS login page" [models]: ./models.html "Introduction to Juju models" [ubuntuSSO]: https://login.ubuntu.com/ "Ubuntu single sign on" -[users]: ./users-models.html "Users and models" [gcedashboard]: https://console.cloud.google.com [gcecredentials]: https://console.developers.google.com/apis/credentials [install]: ./reference-install.html diff --git a/src/en/users-auth.md b/src/en/machine-auth.md similarity index 84% rename from src/en/users-auth.md rename to src/en/machine-auth.md index 5d9cfac9a..6b69d6c6f 100644 --- a/src/en/users-auth.md +++ b/src/en/machine-auth.md @@ -1,16 +1,11 @@ -Title: Machine SSH authentication +Title: Machine authentication TODO: Stuff on user-created models (ssh key and credentials) -# Machine SSH authentication +# Machine authentication -This page explains how SSH authentication works when contacting a Juju -machine. - -## SSH access - -SSH access is managed on a per-model basis. That is, if a public key is added -to a model then that key is placed on all machines (present and future) in that -model. +Juju machines are contacted via the SSH protocol and is managed on a per-model +basis. That is, if a public key is added to a model then that key is placed on +all machines (present and future) in that model. Each Juju machine provides a user account named 'ubuntu' and it is to this account that public keys are added when using the Juju SSH commands @@ -32,12 +27,13 @@ to an individual machine using standard methods (manually copying a key to the `authorized_keys` file or by way of a command such as `ssh-import-id` in the case of Ubuntu). -### Juju ssh +## Juju ssh When using the Juju `ssh` command, Juju's own user rights system imposes an -extra degree of security by permitting access solely from a Juju user, and only -one with sufficient permissions. How this works depends on whether the user is -an admin or a non-admin (see [User types][users]). +extra degree of security by permitting access solely from a Juju user. This +user must also have either 'superuser' controller access or 'admin' model +access. See [Managing models in a multi-user context][multiuser-models] for +more information. For example, to connect to a machine with an id of '0': @@ -49,7 +45,7 @@ An interactive pseudo-terminal (pty) is enabled by default. For the OpenSSH client, this corresponds to the `-t` option ("force pseudo-terminal allocation"). -#### Admin user +### Admin user When a controller is created a passphraseless SSH keypair will be generated and placed under `~/.local/share/juju/ssh`. The public key (`juju_id_rsa.pub`) will @@ -61,7 +57,7 @@ machine. As long as the controller administrator has access to either of the above keys he/she can connect to any machine with `juju ssh`. -#### Regular user +### Regular user In order for a regular Juju user to connect with `juju ssh` the user must: @@ -88,7 +84,7 @@ The second option above, applied to the previous example, will look like this: juju ssh 0 -i ~/.ssh/my-private-key ``` -### Direct SSH access +## Direct SSH access When using a standard SSH client if one's public key has been installed into a model, then, as expected, a connection to the 'ubuntu' user account can be @@ -107,3 +103,4 @@ ssh ubuntu@10.149.29.143 [users]: ./users.md [multiuser-models-access]: ./multiuser.md#models-access +[multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index 8796d5040..e7000cbab 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -55,6 +55,8 @@ navigation: children: - title: Charm bundles location: charms-bundles.md + - title: Machine authentication + location: machine-auth.md - title: Using storage location: charms-storage.md - title: Working with actions diff --git a/src/en/models-adding.md b/src/en/models-adding.md index 61da11904..e043e8010 100644 --- a/src/en/models-adding.md +++ b/src/en/models-adding.md @@ -1,21 +1,19 @@ Title: Adding a model -TODO: What "appropriate command options"? # Adding a model A controller can host multiple models to accommodate different workloads or use cases. When a controller is created, it creates two initial models called 'controller' and 'default', but more models can be added with the `add-model` -command. - -A new model inherits, by default, the cloud credentials used to create the -controller and the SSH keys copied across the model will be those of the -controller model. The administrator can override these defaults with the -appropriate command options. +command. See [Creating a controller][controllers-creating] for details. Model names can be the same when hosted on different controllers, but they must -be unique when hosted on a single controller. Model names can consist only of -lowercase letters, digits, and hyphens (but cannot start with a hyphen). +be unique when hosted on a single controller. + +It is important to understand that credentials used with Juju are always +associated with a model. When creating a model, therefore, a credential is +either specified explicitly or a default is used. Read the +[Credentials][credentials] page for background information. See section [Managing models in a multi-user context][multiuser-models] for information on that subject. @@ -42,6 +40,13 @@ existing credential name of 'jon': juju add-model rackspace-prod --credential jon ``` +Here we're creating model 'han' in a multi-user context. We assign Juju user +'don' as model owner in addition to specifying credential 'ren': + +```bash +juju add-model han --owner don --credential ren +``` + By default, Juju will automatically change to the newly created model. Subsequent commands, unless the `-m` option is used to select a specific model, will operate on this model. This can be confirmed by running the `switch` @@ -64,3 +69,5 @@ case, you can add `--no-switch` option to keep the current model selected. [multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context +[controllers-creating]: ./controllers-creating.md +[credentials]: ./credentials.md diff --git a/src/en/models.md b/src/en/models.md index 258c808b2..668c7bfae 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -191,7 +191,7 @@ Common model management tasks are summarized below. ^# Grant and revoke user access This topic is treated in - [Users and models](./users-models.html#models-and-user-access). + [Working with multiple users](./multiuser.md). diff --git a/src/en/multiuser.md b/src/en/multiuser.md index f2ce7f211..ea5e051b4 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -1,14 +1,23 @@ Title: Working with multiple users TODO: Stuff on user-added models (ssh key and credentials) Check the functionality of admin user access level. This currently appears to do nothing (not destroy models, nor backups) + Add "External users" page when ready # Working with multiple users Juju has an internal user framework that allows for the sharing of controllers -and models. To achieve this, a Juju user can be created that is of a certain -type; be granted specific permissions; and be authenticated in a certain way. +and models. To achieve this, a Juju user can be created, disabled, and have +rights granted and revoked. Users remote to the system that created a +controller can use their own Juju client to log in to the controller and manage +the environment based on the rights conferred. Multiple users can be +accommodated by the same Juju client. -[Machine SSH authentication][users-auth] +Various categories of users can be defined based on the permissions they have +been granted. In turn, these permissions lead to certain abilities. See page +[User types and abilities][users] for an overview. + +!!! Note: + Juju users are not related in any way to the client system users. ## Creating users @@ -18,10 +27,11 @@ There are two ways users are introduced into Juju: administrator 1. with the `add-user` command, which creates a generic user -The second sets up a password but the first is left without one. This is why if -such an admin tries to log out (`logout`) before creating a password the -command will fail and a warning will be displayed. An admin should, therefore, -create a password once the controller is created: +In the second case the user gets a password set up but in the first case the +user is left without one. This is why if such an admin tries to log out +(`logout`) before creating a password the command will fail and a warning will +be emitted. An admin should, therefore, create a password once the controller +is created: ```bash juju bootstrap aws @@ -30,10 +40,7 @@ juju change-user-password In a Juju context, the term "credential" is related to the accessing of a chosen backing cloud, and not to Juju users. See [Credentials][credentials] for -further clarification. - -[User types][users] -[External users][users-external] +guidance. ### Creating a generic user @@ -219,8 +226,8 @@ A controller admin uses the `grant` command to give a user 'read', 'write', or (e.g. `model-config` and `model-defaults`). - `admin`: In addition to 'write' abilities, a user can perform model upgrades (`upgrade-model`) and connect to machines via `juju ssh`. Makes the user an - effective model owner. See [Model owners][users-owners] for commands - available to such a user. + effective model owner. See [Machine authentication][machine-auth] for how + to connect to machines. Here we give 'bob' write access to model 'genesis': @@ -276,9 +283,7 @@ access, three further levels of access can be applied to a controller: - `login`: the standard access level, enabling a user to log in to a controller. - `add-model`: in addition to login access, a user can add and remove models. - - `superuser`: makes a user an effective controller administrator. See - [Controller administrators][users-admins] for commands available to such a - user. + - `superuser`: makes a user an effective controller administrator. The command syntax for controller access is the same as for model access, only without the need to specify a model. As usual, with no controller specified via @@ -339,7 +344,6 @@ currently active one. [users]: ./users.md -[users-auth]: ./users-auth.md -[users-owners]: ./users.md#model-owners -[users-admins]: ./users.md#controller-administrators +[machine-auth]: ./machine-auth.md +[users-external]: ./users-external.md [credentials]: ./credentials.md diff --git a/src/en/users.md b/src/en/users.md index b7898bed9..1ee8d98b4 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -1,16 +1,13 @@ -Title: User types +Title: User types and abilities -# User types +# User types and abilities *This is in connection with the [Working with multiple users][multiuser] page. See that resource for background information.* -There are three kinds of Juju users: controller administrators, model owners, -and regular users. Each user, no matter the kind, is associated with one, and -only one, controller. - -Juju users are not related in any way to the client system users; they are -purely Juju constructs. +There are three types of Juju users that we can speak of: controller +administrators, model owners, and regular users. Each user, no matter the kind, +is associated with one, and only one, controller. A *controller administrator* is a user who has full access to the 'controller' model. This set of users is comprised of the controller creator and any user @@ -27,16 +24,15 @@ A *regular user* is one who is neither a controller administrator nor a model owner. Such a user requires access to a model in order to do anything at the Juju level. -The *operator* is a term used to refer to the actual person who is driving the -Juju client. - -## User abilities +!!! Note: + The *operator* is a term used to refer to the actual person who is driving + the Juju client. The different Juju user types have different abilities based on permissions. They are outlined below. For completeness, the abilities of system users and newly-created users are also included. -### System users +## System users Actions available to a system user and the corresponding Juju commands: @@ -58,7 +54,7 @@ conceivable that multiple controllers exist that use the same cloud resource (public cloud account). Although this will work with Juju, it is a policy decision as to whether this should be allowed. -### Newly-created users +## Newly-created users A newly-created user is automatically granted login access to the controller. Once logged in, the user is allowed to perform the following additional @@ -71,7 +67,7 @@ actions: To do anything further the user must be granted some level of access to a model or be given superuser access to the controller. -### Controller administrators +## Controller administrators Only a controller administrator (the "admin") has the power to perform these actions (in the context of their controller): @@ -87,12 +83,12 @@ actions (in the context of their controller): - Upgrade models (`upgrade-model`) - Manage controller backups (e.g. `create-backup`) -### Model owners +## Model owners A model owner can list users who have access to the model (`users`), destroy the model (`destroy-model`), and upgrade the model (`upgrade-model`). -### Regular users +## Regular users The ability of a regular user depends on the model access rights ('read' or 'write') they have been granted. From ffdfa1c54fc4dcc42acdd34464288edb13931462 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 14 Dec 2018 15:22:39 -0500 Subject: [PATCH 185/311] fix errors --- src/en/machine-auth.md | 4 ++-- src/en/models.md | 4 ++++ src/en/multiuser.md | 13 +++++++++---- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/src/en/machine-auth.md b/src/en/machine-auth.md index 6b69d6c6f..545e7426c 100644 --- a/src/en/machine-auth.md +++ b/src/en/machine-auth.md @@ -69,7 +69,7 @@ In order for a regular Juju user to connect with `juju ssh` the user must: `import-ssh-key`) - be in possession of the corresponding private SSH key -See [Models access][multiuser-models-access] for information on managing user +See [Model access][multiuser-models-access] for information on managing user permissions. In terms of the private key, the easiest way to ensure it is used is to have it @@ -102,5 +102,5 @@ ssh ubuntu@10.149.29.143 [users]: ./users.md -[multiuser-models-access]: ./multiuser.md#models-access +[multiuser-model-access]: ./multiuser.md#model-access [multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context diff --git a/src/en/models.md b/src/en/models.md index 6fbb28236..6e8a15a96 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -38,6 +38,9 @@ Common model management tasks are summarized below. For complete explanation and syntax, see the [command reference page](./commands.html#add-model) or the `juju help add-model` command. + + The [Adding a model][models-adding] page provides a full explanation and + includes examples. @@ -237,3 +240,4 @@ Common model management tasks are summarized below. [charms-bundles-diff]: ./charms-bundles.md#comparing-a-bundle-to-a-model +[models-adding]: ./models-adding.md diff --git a/src/en/multiuser.md b/src/en/multiuser.md index ea5e051b4..8369de1e7 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -201,16 +201,20 @@ new token. ## Managing models in a multi-user context In this section we go over the various ways models can be managed in a -multi-user context. +multi-user context. Subtopics include: + + - Providing model ownership during model creation + - Model access + - Controller access ### Providing model ownership during model creation The model creator becomes, by default, the model owner. However, the creation -process does allow for owner designation. To add model 'arena' and designate -user 'tron' as the owner: +process does allow for owner designation. To add model 'staging' and designate +user 'neo' as the owner: ```bash -juju add-model --owner=tron arena +juju add-model --owner=neo staging ``` See the [Adding a model][models-adding] page for the basics on adding models. @@ -347,3 +351,4 @@ currently active one. [machine-auth]: ./machine-auth.md [users-external]: ./users-external.md [credentials]: ./credentials.md +[models-adding]: ./models-adding.md From 50c74986e2996324b054c89ad7f9956e0c61450d Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Fri, 14 Dec 2018 16:24:37 -0500 Subject: [PATCH 186/311] review and other minor improvements --- src/en/controllers.md | 9 +-- src/en/metadata.yaml | 2 + src/en/models-migrate.md | 4 +- src/en/models.md | 136 ++++++++++++++++----------------------- 4 files changed, 66 insertions(+), 85 deletions(-) diff --git a/src/en/controllers.md b/src/en/controllers.md index 21900fde1..a01d2fc7c 100644 --- a/src/en/controllers.md +++ b/src/en/controllers.md @@ -1,6 +1,5 @@ Title: Controllers -TODO: Figure out the 'block command' situation (including CLI help - text). See 'Restricting command usage' section. The old page lives on. +TODO: Figure out the 'block command' situation (including CLI help text). See 'Restricting command usage' section. The old page lives on. Need examples for each command. Review required @@ -22,8 +21,9 @@ Since a controller can host multiple models, the destruction of a controller must be done with ample consideration since all its models will be destroyed along with it. -In some circumstances you may wish to share a controller or one of its associated -models. Juju provides [multi-user functionality](./users.html) for this purpose. +In some circumstances you may wish to share a controller or one of its +associated models. See page [Working with multiple users][multiuser] for +guidance. ## Minimum requirements @@ -164,3 +164,4 @@ Common tasks are summarized below. [gui]: ./controllers-gui.html [ha]: ./controllers-ha.html [charm-ha]: ./charms-ha.html +[multiuser]: ./multiuser.md diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index e7000cbab..e93a2f35c 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -57,6 +57,8 @@ navigation: location: charms-bundles.md - title: Machine authentication location: machine-auth.md + - title: Migrating models + location: models-migrate.md - title: Using storage location: charms-storage.md - title: Working with actions diff --git a/src/en/models-migrate.md b/src/en/models-migrate.md index dc33b8826..b3ae86047 100644 --- a/src/en/models-migrate.md +++ b/src/en/models-migrate.md @@ -1,7 +1,7 @@ Title: Migrating models -TODO: Needs adding to navigation - How are subnet and end point bindings handled? +TODO: How are subnet and end point bindings handled? Check and add migration resources for different controllers + Review and testing required # Migrating models diff --git a/src/en/models.md b/src/en/models.md index 6e8a15a96..3cbf39e33 100644 --- a/src/en/models.md +++ b/src/en/models.md @@ -1,6 +1,4 @@ Title: Models -TODO: Review required. Convert to abstract links - # Models @@ -15,57 +13,43 @@ immediate use. Models can be added easily at any time. Common model management tasks are summarized below. - - ^# View model status - Use the `juju status` command to view the status of a model: + Use the `status` command to view the status of a model: `juju status [options] [filter pattern ...]` - For complete explanation and syntax, see the - [command reference page](./commands.html#status) or the `juju help - status` command. - + For command line help and syntax run `juju help status`. ^# Add a model - Use the `juju add-model` command to add a model to a controller: + Use the `add-model` command to add a model to a controller: `juju add-model [options] [key=[value] ...]` - For complete explanation and syntax, see the - [command reference page](./commands.html#add-model) or the `juju help - add-model` command. + For command line help and syntax run `juju help add-model`. The [Adding a model][models-adding] page provides a full explanation and includes examples. - ^# List all models - Use the `juju models` command to list all models for a controller: + Use the `models` command to list all models for a controller: `juju models [options]` - For complete explanation and syntax, see the - [command reference page](./commands.html#models) or the `juju help - models` command. - + For command line help and syntax run `juju help models`. ^# Examine a model - Use the `juju show-model` command to examine a specific model: + Use the `show-model` command to examine a specific model: `juju show-model [options]` - For complete explanation and syntax, see the - [command reference page](./commands.html#show-model) or the - `juju help show-model` command. - + For command line help and syntax run `juju help show-model`. ^# Compare a bundle to a model @@ -74,6 +58,8 @@ Common model management tasks are summarized below. `juju diff-bundle [options] ` + For command line help and syntax run `juju help diff-bundle`. + This topic is treated on the [Charm bundles][charms-bundles-diff] page. @@ -83,38 +69,31 @@ Common model management tasks are summarized below. machines in the model. For instance, a logging level and API port can be stipulated. - This is a complex subject. See [Model configuration](./models-config.html). - + This is a complex subject. See [Model configuration][models-config]. ^# Set constraints for a model Charm constraints can be managed at the model level. This will affect all - charms used in the model unless overridden by constraints set at the - application level. Constraints are used to select minimum requirements for any - future machines Juju may create. For instance, a constraint may be set so that - machines have a minimum amount of disk space on their root drive. + charms used in the model unless overridden. Constraints are used to select + minimum requirements for any future machines Juju may create. This is a complex subject. See - [Using constraints](./charms-constraints.html#setting-constraints-for-a-model). - + [Setting constraints for a model][charms-constraints-models]. ^# Destroy a model - Use the `juju destroy-model` command to remove a model from a controller: + Use the `destroy-model` command to remove a model from a controller: `juju destroy-model [options] ` - For complete explanation and syntax, see the - [command reference page](./commands.html#destroy-model) or the `juju help - destroy-model` command. - + For command line help and syntax run `juju help destroy-model`. ^# Change models - Use the `juju switch` command to go from one model to another: + Use the `switch` command to change from one model to another: `juju switch [|<:model>|:|]` @@ -138,29 +117,24 @@ Common model management tasks are summarized below. `juju switch foo:` Selects the last used model in controller 'foo' - For complete explanation and syntax, see the - [command reference page](./commands.html#switch) or the `juju help switch` - command. + For command line help and syntax run `juju help switch`. ^# Migrate models - Use the `juju migrate` command to move a model from one controller to - another. This is useful for load balancing when a controller is too busy, or - as a way to upgrade a model's controller to a newer Juju version. + Use the `migrate` command to migrate a model from one controller to another. `juju migrate [options] ` - - For a complete explanation, see [migrating models](./models-migrate.html), - the [command reference page](./commands.html#migrate) or the `juju help - migrate` command. + For command line help and syntax run `juju help migrate`. + + For a complete explanation see the [Migrating models][models-migrate] page. ^# Provide SSH access - Use the `juju add-ssh-key` and `juju import-ssh-key` commands to provide SSH - access to all machines, present and future, in a model: + Use the `add-ssh-key` and `import-ssh-key` commands to provide SSH access to + all machines, present and future, in a model: `juju add-ssh-key ` @@ -168,53 +142,50 @@ Common model management tasks are summarized below. `juju import-ssh-key :` - For complete explanation and syntax, see the - [command reference page](./commands.html#add-ssh-key) or the - `juju help add-ssh-key` or the `juju help import-ssh-key` commands. + For command line help and syntax run `juju help add-ssh-key` or + `juju help import-ssh-key`. + For in-depth coverage see page [Machine authentication][machine-auth]. ^# List SSH access keys - Use the `juju ssh-keys` command to list SSH keys currently permitting - access to all machines, present and future, in a model: + Use the `ssh-keys` command to list SSH keys currently permitting access to + all machines, present and future, in a model: `juju ssh-keys [options]` - For complete explanation and syntax, see the - [command reference page](./commands.html#ssh-keys) or the `juju help - ssh-keys` command. - + For command line help and syntax run `juju help ssh-keys`. ^# Remove SSH access - Use the `juju remove-ssh-key` command to remove SSH access to all machines, + Use the `remove-ssh-key` command to remove SSH access to all machines, present and future, from a model: `juju remove-ssh-key ...` - For complete explanation and syntax, see the - [command reference page](./commands.html#remove-ssh-key) or the `juju help - remove-ssh-key` command. - + For command line help and syntax run `juju help remove-ssh-key`. ^# Grant and revoke user access - This topic is treated in - [Working with multiple users](./multiuser.md). - + If you're using multiple Juju users you will need to manage access to your + models. See page [Working with multiple users][multiuser] for a full + explanation. ^# View logs + + Use the `debug-log` command to examine logs on a per-model basis: + + `juju debug-log [options]` - Juju logs are viewed at the model level. This allows inspection of - activities occuring on multiple Juju machines simultaneously. Due to the - expected large volume of data, advanced filtering is available. - - This is a complex subject. See [Juju logs](./troubleshooting-logs.html). + This allows inspection of activities occurring on multiple Juju machines + simultaneously. Due to the expected large volume of data, advanced filtering + is available. + A full explanation is provided on the [Juju logs][juju-logs] page. ^# Upgrade a model @@ -223,21 +194,28 @@ Common model management tasks are summarized below. running on every machine Juju creates. This upgrade process does not pertain to the Juju software package installed on a client system. - This is a complex subject. See [Upgrading models](./models-upgrade.html). - + See [Upgrading models][models-upgrade] for complete coverage. ^# Cross model relations Traditionally, when adding a relation between two applications (see - [Charm relations](./charms-relations.html)) the applications reside within - the same model and controller. It is possible, however, to break out of this - paradigm by employing *cross model relations*. + [Charm relations][charms-relations]) the applications reside within the same + model and controller. It is possible to overcome this limitation by + employing *cross model relations*. - This is a complex subject. See [Cross model relations](./models-cmr.html). + This topic is covered on the [Cross model relations][models-cmr] page. -[charms-bundles-diff]: ./charms-bundles.md#comparing-a-bundle-to-a-model +[models-cmr]: ./models-cmr.md [models-adding]: ./models-adding.md +[models-config]: ./models-config.md +[models-migrate]: ./models-migrate.md +[models-upgrade]: ./models-upgrade.md +[charms-relations]: ./charms-relations.md +[charms-bundles-diff]: ./charms-bundles.md#comparing-a-bundle-to-a-model +[charms-constraints-models]: ./charms-constraints.md#setting-constraints-for-a-model +[juju-logs]: ./troubleshooting-logs.md +[multiuser]: ./multiuser.md From 1f0b32b1505c5ce304830a5813826eda2eae73dc Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 15 Dec 2018 02:00:02 -0500 Subject: [PATCH 187/311] lots of improvements --- src/en/machine-auth.md | 46 ++++++++++++++++++++++++----------------- src/en/models-adding.md | 8 +++++++ src/en/multiuser.md | 7 +++++++ src/en/users.md | 6 +++--- 4 files changed, 45 insertions(+), 22 deletions(-) diff --git a/src/en/machine-auth.md b/src/en/machine-auth.md index 545e7426c..8d725c7f5 100644 --- a/src/en/machine-auth.md +++ b/src/en/machine-auth.md @@ -31,9 +31,9 @@ case of Ubuntu). When using the Juju `ssh` command, Juju's own user rights system imposes an extra degree of security by permitting access solely from a Juju user. This -user must also have either 'superuser' controller access or 'admin' model -access. See [Managing models in a multi-user context][multiuser-models] for -more information. +user must also have 'admin' model access. +See [Managing models in a multi-user context][multiuser-models] for help on +assigning user permissions. For example, to connect to a machine with an id of '0': @@ -45,32 +45,39 @@ An interactive pseudo-terminal (pty) is enabled by default. For the OpenSSH client, this corresponds to the `-t` option ("force pseudo-terminal allocation"). -### Admin user +### SSH keys and models -When a controller is created a passphraseless SSH keypair will be generated and +When a model is created a passphraseless SSH keypair will be generated and placed under `~/.local/share/juju/ssh`. The public key (`juju_id_rsa.pub`) will -be installed in the 'ubuntu' account on every machine created within every -model belonging to this controller. During creation, if there is an existing -public key named `~/.ssh/id_rsa.pub` then it will also be placed on every -machine. +be installed in the 'ubuntu' account on every machine created within the model. +Any key located at `~/.ssh/id_rsa.pub` will also be placed in the model. -As long as the controller administrator has access to either of the above keys -he/she can connect to any machine with `juju ssh`. +This means that a model creator will always be able to connect to any machine +within that model (with `juju ssh`) without having to add keys since the +creator is also granted 'admin' model access by default (see +[Adding a model][models-adding] for more information). Recall that the creation +of a controller effectively produces two models: 'controller' and 'default'. +This provides the initial controller administrator access to keys and models +out of the box. -### Regular user +### Providing access to non-initial controller admin Juju users -In order for a regular Juju user to connect with `juju ssh` the user must: +In order for a non-initial controller admin user to connect with `juju ssh` +that user must: - be created (`add-user`) - - have registered a controller (`register`) + - have registered the controller (`register`) - be logged in (`login`) - - have 'admin' rights to the model (`grant`) - - have their public SSH key added to the model by an admin (`add-ssh-key` or - `import-ssh-key`) + - have 'admin' access to the model + - have their public SSH key reside within the model - be in possession of the corresponding private SSH key -See [Model access][multiuser-models-access] for information on managing user -permissions. +As previously explained, 'admin' model access and installed model keys can be +obtained by creating the model. Otherwise access needs to be granted (`grant`) +by a controller admin and keys need to be added (`add-ssh-key` or +`import-ssh-key`) by a controller admin or the model admin. + +See [Model access][multiuser-model-access] for how to grant rights to a model. In terms of the private key, the easiest way to ensure it is used is to have it stored as `~/.ssh/id_rsa`. Otherwise, you can do one of two things: @@ -104,3 +111,4 @@ ssh ubuntu@10.149.29.143 [users]: ./users.md [multiuser-model-access]: ./multiuser.md#model-access [multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context +[models-adding]: ./models-adding.md diff --git a/src/en/models-adding.md b/src/en/models-adding.md index e043e8010..307a0c537 100644 --- a/src/en/models-adding.md +++ b/src/en/models-adding.md @@ -15,6 +15,13 @@ associated with a model. When creating a model, therefore, a credential is either specified explicitly or a default is used. Read the [Credentials][credentials] page for background information. +The model creator, by default, is granted 'admin' model access by default. This +includes the two initial models created at controller-creation time. This +assists in connecting to machines within the model with `juju ssh` (see +[SSH keys and models][machine-auth-ssh-keys]). An exception to this is when the +creator explicitly designates another user as 'owner'. In this case, the +creator does not get 'admin' model access. + See section [Managing models in a multi-user context][multiuser-models] for information on that subject. @@ -71,3 +78,4 @@ case, you can add `--no-switch` option to keep the current model selected. [multiuser-models]: ./multiuser.md#managing-models-in-a-multi-user-context [controllers-creating]: ./controllers-creating.md [credentials]: ./credentials.md +[machine-auth-ssh-keys]: ./machine-auth.md#ssh-keys-and-models diff --git a/src/en/multiuser.md b/src/en/multiuser.md index 8369de1e7..825e735cd 100644 --- a/src/en/multiuser.md +++ b/src/en/multiuser.md @@ -104,6 +104,10 @@ of a model to grant access to that model with "juju grant". The name of the original controller, in this case 'lxd-bionic-1', is offered as a default controller name. +!!! Note: + A user can be acted upon (e.g. granted permissions) prior to that user + registering the controller. + ## Logins and logouts A user who has just registered a controller is automatically logged in to that @@ -255,6 +259,9 @@ Model Cloud/Region Status Access Last connection admin/euphoric* localhost/localhost available read never connected ``` +Notice how the model name is prepended with the remote user's name. The name +is the 'owner' of the model. + Access can be viewed on a per-model basis by using the `show-model` command. Here we query model 'mara': diff --git a/src/en/users.md b/src/en/users.md index 1ee8d98b4..0fb07c357 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -16,9 +16,9 @@ There is no overarching "Juju administrator" since multiple controllers, and therefore multiple controller administrators, are possible. Nevertheless, this user is usually what people refer to as "the admin". -A *model owner* is a user who has full access to a model. This set of users is -comprised of the model creator and any user who has been granted 'admin' access -to the model. +A *model owner* has some specific administrative powers over a model. By +default, the owner is the model creator but an owner can also be explicitly +assigned during creation-time. A *regular user* is one who is neither a controller administrator nor a model owner. Such a user requires access to a model in order to do anything at the From df5c2e541a57e76b613abdd9c0ec1f23c0463291 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Sat, 15 Dec 2018 21:20:48 -0500 Subject: [PATCH 188/311] mild improvements --- src/en/machine-auth.md | 6 +++--- src/en/users.md | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/en/machine-auth.md b/src/en/machine-auth.md index 8d725c7f5..b6eac662c 100644 --- a/src/en/machine-auth.md +++ b/src/en/machine-auth.md @@ -48,9 +48,9 @@ allocation"). ### SSH keys and models When a model is created a passphraseless SSH keypair will be generated and -placed under `~/.local/share/juju/ssh`. The public key (`juju_id_rsa.pub`) will -be installed in the 'ubuntu' account on every machine created within the model. -Any key located at `~/.ssh/id_rsa.pub` will also be placed in the model. +placed under `~/.local/share/juju/ssh` and public key `juju_id_rsa.pub` will be +placed in the model. Any key located at `~/.ssh/id_rsa.pub` will also be +used. This means that a model creator will always be able to connect to any machine within that model (with `juju ssh`) without having to add keys since the diff --git a/src/en/users.md b/src/en/users.md index 0fb07c357..759bba04b 100644 --- a/src/en/users.md +++ b/src/en/users.md @@ -1,4 +1,6 @@ Title: User types and abilities +TODO: bug tracking: https://bugs.launchpad.net/bugs/1808661 + bug tracking: https://bugs.launchpad.net/bugs/1808662 # User types and abilities From 0517b8f0e595201f7ff85f79ee60b262e1f0ab94 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 20 Dec 2018 15:53:53 -0500 Subject: [PATCH 189/311] add entry to menu --- src/en/metadata.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/en/metadata.yaml b/src/en/metadata.yaml index e93a2f35c..9749f3660 100644 --- a/src/en/metadata.yaml +++ b/src/en/metadata.yaml @@ -23,6 +23,8 @@ navigation: location: charms-deploying.md - title: Using constraints location: charms-constraints.md + - title: Configuring models + location: models-config.md - title: Configuring applications location: charms-config.md - title: Managing relations From f4e7a838881597eebe5ba036bb1ebea9a87ee5ab Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 26 Dec 2018 11:58:10 -0500 Subject: [PATCH 190/311] edit home page; minor improvements to k8s pages --- src/en/clouds-k8s.md | 14 +++++++++----- src/en/index.md | 7 ++++--- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/src/en/clouds-k8s.md b/src/en/clouds-k8s.md index 4fdc69227..35678b8e8 100644 --- a/src/en/clouds-k8s.md +++ b/src/en/clouds-k8s.md @@ -13,10 +13,14 @@ Kubernetes ("k8s") provides a flexible architecture for managing containerised applications at scale. See the [Kubernetes documentation][upstream-kubernetes-docs] for more information. -Juju has the ability to add a Kubernetes cluster to its known list of clouds, -thereby treating the cluster like it does any other cloud. There are some -differences to working with such a cloud and they are covered in the next -section. +The objective of this page is how to add an existing Kubernetes cluster to +Juju. It is not about showing how to install Kubernetes *with* Juju, although +we do give pointers on how to do so. + +Essentially, Juju is able to treat the added cluster as it does any other of +its known clouds (i.e. create models and deploy charms). There are some +differences to working with such a cloud and they are called out in the +following section. This document refers to page [Persistent storage and Kubernetes][charms-storage-k8s] in a few places. You @@ -91,7 +95,7 @@ suggestions: [Spell Walkthrough][upstream-conjure-up-guide] - Use [MicroK8s][upstream-microk8s]. This gives you get a local, fully compliant Kubernetes deployment with dynamic persistent volume support. See - tutorial [Using Juju with microk8s][tutorial-microk8s]. + tutorial [Using Juju with MicroK8s][tutorial-microk8s]. - Use a bundle made for the major cloud vendors. There are special "integrator" charms that assist with such deployments. [Search the Charm Store][charm-store-staging-integrator] for 'integrator'. diff --git a/src/en/index.md b/src/en/index.md index 9f9fdf488..e7cea2c50 100644 --- a/src/en/index.md +++ b/src/en/index.md @@ -28,19 +28,20 @@ homepage: true
  • New features in 2.5 ›
  • Remote and clustered LXD clouds ›
  • Oracle OCI cloud support ›
    • -
  • Release Notes ›
    • +
  • Using Kubernetes with Juju ›

    • Explore Juju

    From 610398c22529e0754a7228ea57b14fb0b23cedd8 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 26 Dec 2018 16:28:49 -0500 Subject: [PATCH 191/311] fill in and remove old upgrade series page --- src/en/charms-bundles.md | 2 +- src/en/controllers-creating.md | 14 +++ src/en/howto-updateseries.md | 179 ------------------------------ src/en/index.md | 4 +- src/en/reference-release-notes.md | 4 + src/en/upgrade-series.md | 6 - src/en/whats-new.md | 71 ++++++------ 7 files changed, 60 insertions(+), 220 deletions(-) delete mode 100644 src/en/howto-updateseries.md diff --git a/src/en/charms-bundles.md b/src/en/charms-bundles.md index 41c3558d6..5720506ad 100644 --- a/src/en/charms-bundles.md +++ b/src/en/charms-bundles.md @@ -706,7 +706,7 @@ case you would simply reference the bundle name, such as 'wiki-simple': juju diff-bundle wiki-simple ``` -## Saving a bundle and next steps +## Saving a bundle If you have created your own bundle you will probably want to save it. This is done with the `export-bundle` command, which exports a single model diff --git a/src/en/controllers-creating.md b/src/en/controllers-creating.md index 45e98eded..6c679a53e 100644 --- a/src/en/controllers-creating.md +++ b/src/en/controllers-creating.md @@ -29,6 +29,7 @@ be done at controller-creation time: - [Create a controller using configuration values][#create-a-controller-using-configuration-values] - [Create a controller using a non-default region][#create-a-controller-using-a-non-default-region] - [Create a controller using a different MongoDB profile][#create-a-controller-using-a-different-mongodb-profile] + - [Use a custom charm store][#use-a-custom-charm-store] - [Change timeout and retry delays][#change-timeout-and-retry-delays] - [Create a new controller without changing contexts][#create-a-new-controller-without-changing-contexts] - [Configuring/enabling a remote syslog server][#configuring/enabling-a-remote-syslog-server] @@ -130,6 +131,18 @@ your controller uses when it is created, use: juju bootstrap --config mongo-memory-profile=low ``` +### Use a custom charm store + +Sometimes the charms you're interested in do not yet reside in the default +production charm store (`https://api.jujucharms.com/charmstore`). In this case +you can configure Juju to pull charms from an alternate source at controller +creation time. Below, we create an OCI controller and pass the staging store +URL: + +```bash +juju bootstrap --config charmstore-url=https://api.staging.jujucharms.com/charmstore oci +``` + ### Change timeout and retry delays You can change the default timeout and retry delays used by Juju by setting the @@ -250,6 +263,7 @@ how to do this. [#create-a-controller-using-configuration-values]: #create-a-controller-using-configuration-values [#create-a-controller-using-a-non-default-region]: #create-a-controller-using-a-non-default-region [#create-a-controller-using-a-different-mongodb-profile]: #create-a-controller-using-a-different-mongodb-profile +[#use-a-custom-charm-store]: #use-a-custom-charm-store [#change-timeout-and-retry-delays]: #change-timeout-and-retry-delays [#create-a-new-controller-without-changing-contexts]: #create-a-new-controller-without-changing-contexts [#configuring/enabling-a-remote-syslog-server]: #configuring/enabling-a-remote-syslog-server diff --git a/src/en/howto-updateseries.md b/src/en/howto-updateseries.md deleted file mode 100644 index 27ca6b02c..000000000 --- a/src/en/howto-updateseries.md +++ /dev/null @@ -1,179 +0,0 @@ -Title: Update the series of a controller or machine -TODO: Warning: Juju versions hardcoded - Should eventually remove the two "prior to 2.3" Notes - -# Update the series of a controller or machine - -It may sometimes be necessary to upgrade the operating system version (i.e. -series) of the controller and/or the machines. - -## Upgrading a controller - -### Prerequisites - - 1. Controller admin privileges - 1. An available instance resource in the controller's cloud - -### Recommended method - -At this time there is no way to update the series of a controller. A new -controller will be needed, after which a migration of models from the old -controller to the new one must be performed. - -Create the new controller now. A series can be explicitly set for all -newly-created models (if desired): - -```bash -juju bootstrap --config default-series= -``` - -The controller itself will be deployed using the latest LTS Ubuntu release. Use -option `bootstrap-series` to select something else. - -Now migrate existing models by following the [Migrating models][models-migrate] -page. - -To ensure that all new machines will run the new series set the default series -at the model level. For each migrated model: - -```bash -juju model-config -m default-series= -``` - -Destroy the old controller when done. - -Note that the series running on any existing Juju machines have not yet been -affected (see next section). - -## Upgrading a machine/unit - -For the purpose of this guide, a unit '0' of application 'ghost' which resides -on machine '1' will be used. The series will be updated from 'trusty' to -'xenial'. - -### Prerequisites - - 1. Controller admin privileges - 1. All the charms deployed on the machine must support the new series. - -### Recommended method - -First, for every application, specify the new series: - -```bash -juju set-series ghost xenial -``` - -Then add a new unit of the application to replace each existing unit and remove -the old units: - -```bash -juju add-unit ghost -juju remove-unit ghost/0 -``` - -If you are using a version prior to 2.3 follow the instructions for -[updating an application's series][app-update] before adding and removing -units. - -You are now done. - -### Alternative method - -In some cloud environments, there may not be the resources to update using the -above recommended method. Instead we need to upgrade the existing machine -manually and update the agent data, as shown here: - -!!! Negative "Warning": - This method should be approached with caution. After the series is updated - on an existing machine, the unit agent may not restart cleanly depending on - software dependencies (e.g. software installed with `pip` may need to be - installed in a new location or an application's version was updated - without intent). - -#### Update series for new units - -!!! Note: - If you are using a version of Juju prior to 2.3 follow the instructions for - [updating an application's series][app-update]. - -Let Juju know what series should be used for any new units of the application: - -```bash -juju set-series ghost xenial -``` - -#### Upgrade the existing machine - -!!! Note: - If you are using a version prior to 2.3 follow the instructions for - [updating an machine's series][mach-update]. - -Start by logging in to the machine: - -```bash -juju ssh ghost/0 -``` - -Then follow the [Ubuntu Server Guide][serverguide-upgrade] on upgrading an -Ubuntu release. Be sure to read the [Release Notes][ubuntu-releases] of the -target version. - -If asked during the upgrade, it's recommended to keep currently-installed -versions of configuration files. - -#### Update agent data on the upgraded machine - -!!! Negative "Warning": - If the Python version has changed between the two series **and** the charm - uses `pip` to install packages then it will be necessary to force the unit - to install the new Python packages by running the following command on the - unit's machine prior to restarting the unit's service: - `sudo rm /var/lib/juju/agents/unit*/charm/wheelhouse/.bootstrapped` . - -Update the agent data on the newly updated machine/unit appropriate for the new -series and restart the agents: - -```bash -juju ssh ghost/0 -- sudo juju-updateseries --from-series trusty --to-series xenial --start-agents -``` - -#### Verify the agents are running - -On every machine, there is a machine service agent and, for each running unit, -a unit service agent. To check that they restarted properly after the upgrade: - -```bash -sudo systemctl status jujud* -``` - -Sample output: - -```no-highlight -● jujud-unit-ghost-0.service - juju unit agent for ghost/0 - Loaded: loaded (/var/lib/juju/init/jujud-unit-ghost-0/jujud-unit-ghost-0.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2017-10-04 22:07:13 UTC; 2min 39s ago - -● jujud-machine-1.service - juju agent for machine-1 - Loaded: loaded (/var/lib/juju/init/jujud-machine-1/jujud-machine-1.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2017-10-04 22:07:13 UTC; 2min 39s ago -``` - -#### Let Juju know of the upgraded machines and agents - -Once all machines and agents have been updated we need to inform Juju of this -fact. Here we refer to our example machine with an ID of '1': - -```bash -juju set-series 1 xenial -``` - - - - -[models-migrate]: ./models-migrate.html -[app-update]: https://jujucharms.com/docs/2.2/howto-applicationupdateseries -[mach-update]: https://jujucharms.com/docs/2.2/howto-machineupdateseries -[serverguide-upgrade]: https://help.ubuntu.com/lts/serverguide/installing-upgrading.html -[ubuntu-releases]: https://wiki.ubuntu.com/Releases -[systemd]: https://wiki.ubuntu.com/SystemdForUpstartUsers diff --git a/src/en/index.md b/src/en/index.md index e7cea2c50..1a0a3e4b0 100644 --- a/src/en/index.md +++ b/src/en/index.md @@ -40,8 +40,8 @@ homepage: true models, and the Juju  client › -
  • Setting up static Kubernetes storage ›
    • -
  • Using Juju with MicroK8s ›
    • +
  • Setting up static Kubernetes storage ›
    • +
  • Using Juju with MicroK8s ›
    • diff --git a/src/en/reference-release-notes.md b/src/en/reference-release-notes.md index 668b6f7e4..8c42e67f8 100644 --- a/src/en/reference-release-notes.md +++ b/src/en/reference-release-notes.md @@ -5,6 +5,10 @@ Title: Juju Release Notes This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available [here][release-notes-1]. +^# Juju 2.5.0 + + *Stay tuned.* + ^# Juju 2.4.7 This is a bug fix release and includes the fixes below: diff --git a/src/en/upgrade-series.md b/src/en/upgrade-series.md index 1e379a6cd..e611cea5c 100644 --- a/src/en/upgrade-series.md +++ b/src/en/upgrade-series.md @@ -1,13 +1,7 @@ Title: Upgrading a machine series TODO: warning: ubuntu code names hardcoded bug tracking: https://bugs.launchpad.net/juju/+bug/1797399 - bug tracking: https://bugs.launchpad.net/juju/+bug/1797593 - bug tracking: https://bugs.launchpad.net/juju/+bug/1797595 bug tracking: https://bugs.launchpad.net/juju/+bug/1797388 - bug tracking: https://bugs.launchpad.net/juju/+bug/1797396 - bug tracking: https://bugs.launchpad.net/juju/+bug/1797968 - bug tracking: https://bugs.launchpad.net/juju/+bug/1798094 - bug tracking: https://bugs.launchpad.net/juju/+bug/1798097 # Upgrading a machine series diff --git a/src/en/whats-new.md b/src/en/whats-new.md index 2fab4245d..b690d0c51 100644 --- a/src/en/whats-new.md +++ b/src/en/whats-new.md @@ -2,39 +2,39 @@ Title: What's new in 2.5 # What's new in 2.5 -??????? +The major new features in this release are summarised below. See the +[2.5 release notes][release-notes] for full details. -For full details on this release, see the [2.5 release notes][release-notes]. +## Kubernetes "cloud" support -If you are new to Juju, you will probably want to read the -[Getting started][getting-started] guide first. +Juju has been able to install a Kubernetes cluster for a while now. However, +only until now is Juju able to take a pre-existing cluster and add it to its +list of backing clouds. This renders the cluster available for charm +deployment. Kubernetes-specific charms are naturally required. -## Kubernetes support - -See [][]. +See [Using Kubernetes with Juju][clouds-k8s]. ## Remote LXD support and LXD clustering A remote LXD cloud is now possible. Like other custom clouds, it is added via -the enhanced `add-cloud` command. The Juju client can then request a controller -be created on the remote LXD host. This naturally bolsters the already -supported LXD clustering feature; both features are expected to be used in -tandem. +the `add-cloud` command. The Juju client can then request a controller be +created on the remote LXD host. This naturally bolsters the already supported +LXD clustering feature; both features are expected to be used in tandem. Placement directives are supported for LXD clustering. You can specify upon which LXD host (cluster node) a Juju machine will be created. These nodes effectively become availability zones for a LXD clustered cloud. -See [][]. +See [Adding a remote LXD cloud][clouds-lxd-advanced-remote] and +[LXD clustering][clouds-lxd-advanced-clustering]. ## Oracle Cloud Infrastructure (OCI) support OCI is the new cloud framework from Oracle and Juju now supports it out of the -box. Juju's cloud name for this cloud is 'oci'. At this time both OCI and -Oracle Classic are supported but it is expected that Classic will eventually -be obsoleted. +box. Juju's cloud name for this cloud is 'oci' and it replaces the legacy +Oracle cloud of 'oracle'. -See [][]. +See [Using Oracle OCI with Juju][clouds-oci]. ## Rework of machine series upgrades @@ -47,34 +47,31 @@ machines hosting controllers is not supported and the documented method of creating a new controller and migrating models is still the recommended procedure. -See [][]. +See [Upgrading a machine series][upgrade-series]. ## Charm support for LXD profiles -Juju now supports charms that include a LXD profile. A profile is applied -to a LXD container that the charm is deployed into. Some hardcoded security -checks are applied automatically when such a charm is deployed and profile -information is exposed at the machine level with the `status` and -`show-machine` commands. +Juju now supports charms that include a LXD profile. A profile is applied to a +LXD container that the charm is deployed into. Some hardcoded security checks +are applied automatically when such a charm is deployed and profile information +is exposed at the machine level with the `status` and `show-machine` commands. -See [][]. +See [Charms and LXD profiles][clouds-lxd-advanced-profiles]. ## New command for saving a bundle A model's configuration can now be saved as a bundle at the command line using -the new `export-bundle` command. Previously, the Juju GUI was needed to save -a bundle. +the new `export-bundle` command. Previously, the Juju GUI was needed for this. -See [][]. +See [Saving a bundle][charms-bundles-export]. ## New command for comparing a bundle and model - A model and a bundle can now be compared using the new `diff-bundle` command. This will help in complex enterprise setups where changes have been made to a model yet a new bundle deployment of the initial model is desired. -See [][]. +See [Comparing a bundle to a model][charms-bundles-diff]. ## Enhancements for adding OpenStack clouds @@ -84,24 +81,34 @@ recognises certain environment variables used by OpenStack - typically via its `novarc` file. The corresponding values will be used as default values when `add-cloud` is used in interactive mode. -See [][]. +See [Adding an OpenStack Cloud][clouds-openstack-adding]. ## New command for assigning a remote credential to a model Occasionally there is the need to change (or set) what remote credential is assigned to a model. This is now possible via the new `set-credential` command. -See [][]. +See [Changing a remote credential for a model][credentials-set-credential]. ## Charm Store controller configuration key added A custom Charm Store can be configured by specifying a URL during the creation of a controller (`bootstrap`). -See [][]. +See [Use a custom charm store][controllers-creating-charmstore-url]. -[getting-started]: ./getting-started.md [release-notes]: ./reference-release-notes.md#juju_2.5.0 +[clouds-k8s]: ./clouds-k8s.md +[clouds-lxd-advanced-remote]: ./clouds-lxd-advanced.md#adding-a-remote-lxd-cloud +[clouds-lxd-advanced-clustering]: ./clouds-lxd-advanced.md#lxd-clustering +[clouds-oci]: ./clouds-oci.md +[upgrade-series]: ./upgrade-series.md +[clouds-lxd-advanced-profiles]: ./clouds-lxd-advanced.md#charms-and-lxd-profiles +[charms-bundles-export]: ./charms-bundles.md#saving-a-bundle +[charms-bundles-diff]: ./charms-bundles.md#comparing-a-bundle-to-a-model +[clouds-openstack-adding]: ./help-openstack.md#adding-an-openstack-cloud +[credentials-set-credential]: ./credentials.md#changing-a-remote-credential-for-a-model +[controllers-creating-charmstore-url]: ./controllers-creating.md#use-a-custom-charm-store From b86ca438df1203f583f95cf5463f3317c3532438 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Thu, 27 Dec 2018 17:08:03 -0500 Subject: [PATCH 192/311] update commands --- src/en/commands.md | 2456 +++++++++++++++++++++++++++++--------------- 1 file changed, 1654 insertions(+), 802 deletions(-) diff --git a/src/en/commands.md b/src/en/commands.md index 52b7d1862..aa2ea601f 100644 --- a/src/en/commands.md +++ b/src/en/commands.md @@ -1,14 +1,12 @@ -Title: Juju command reference +Title:Juju commands and usage -# Juju command reference +# Juju Command reference -You can get a list of all Juju commands by invoking `juju help commands` in a -terminal. +You can get a list of all Juju commands by invoking `juju help commands` in a terminal. To drill down into each command use `juju help `. -This same information is also provided below. Click on a command to view -information on it. +This same information is also provided below. Click on a command to view information on it. ^# actions @@ -61,7 +59,7 @@ information on it. **Summary:** - Adds a user-defined cloud to Juju from among known cloud types. + Adds a cloud definition to Juju. **Options:** @@ -71,19 +69,41 @@ information on it. _--replace (= false)_ - Overwrite any existing cloud information + Overwrite any existing cloud information for <cloud name> **Details:** - A cloud definition file has the following YAML format: + Juju needs to know how to connect to clouds. A cloud definition + describes a cloud's endpoints and authentication requirements. Each + definition is stored and accessed later as . + + If you are accessing a public cloud, running add-cloud unlikely to be + necessary. Juju already contains definitions for the public cloud + providers it supports. + + add-cloud operates in two modes: + + juju add-cloud + juju add-cloud + + When invoked without arguments, add-cloud begins an interactive session + designed for working with private clouds. The session will enable you + to instruct Juju how to connect to your private cloud. + + When is provided with , + Juju stores that definition its internal cache directly after + validating the contents. - clouds: + If already exists in Juju's cache, then the `--replace` + option is required. - mycloud: + A cloud definition file has the following YAML format: - type: openstack + clouds: # mandatory + mycloud: # argument + type: openstack # , see below auth-types: [ userpass ] regions: @@ -91,15 +111,28 @@ information on it. endpoint: https://london.mycloud.com:35574/v3.0/ - If the named cloud already exists, the `--replace` option is required to - overwrite its configuration. + for private clouds: + - lxd + - maas + - manual + - openstack + - vsphere + + for public clouds: - Known cloud types: azure, cloudsigma, ec2, gce, joyent, lxd, maas, manual, - openstack, rackspace + - azure + - cloudsigma + - ec2 + - gce + - joyent + - oci **Examples:** - juju add-cloud mycloud ~/mycloud.yaml + juju add-cloud + juju add-cloud mycloud ~/mycloud.yaml + juju add-cloud --replace mycloud ~/mycloud2.yaml + **See also:** @@ -150,6 +183,12 @@ information on it. application-id: application-password: subscription-id: + lxd: + + : + + auth-type: interactive + trust-password: A "credential name" is arbitrary and is used solely to represent a set of credentials, of which there may be multiple per cloud. @@ -170,8 +209,9 @@ information on it. **Examples:** - juju add-credential google - juju add-credential aws -f ~/credentials.yaml + juju add-credential google + juju add-credential aws -f ~/credentials.yaml + **See also:** @@ -218,9 +258,10 @@ information on it. **Examples:** - juju add-k8s myk8scloud - KUBECONFIG=path-to-kubuconfig-file juju add-k8s myk8scloud --cluster-name=my_cluster_name - kubectl config view --raw | juju add-k8s myk8scloud --cluster-name=my_cluster_name + juju add-k8s myk8scloud + KUBECONFIG=path-to-kubuconfig-file juju add-k8s myk8scloud --cluster-name=my_cluster_name + kubectl config view --raw | juju add-k8s myk8scloud --cluster-name=my_cluster_name + **See also:** @@ -298,16 +339,17 @@ information on it. **Examples:** - juju add-machine (starts a new machine) - juju add-machine -n 2 (starts 2 new machines) - juju add-machine lxd (starts a new machine with an lxd container) - juju add-machine lxd -n 2 (starts 2 new machines with an lxd container) - juju add-machine lxd:4 (starts a new lxd container on machine 4) - juju add-machine --constraints mem=8G (starts a machine with at least 8GB RAM) - juju add-machine ssh:user@10.10.0.3 (manually provisions machine with ssh) - juju add-machine winrm:user@10.10.0.3 (manually provisions machine with winrm) - juju add-machine zone=us-east-1a (start a machine in zone us-east-1a on AWS) - juju add-machine maas2.name (acquire machine maas2.name on MAAS) + juju add-machine (starts a new machine) + juju add-machine -n 2 (starts 2 new machines) + juju add-machine lxd (starts a new machine with an lxd container) + juju add-machine lxd -n 2 (starts 2 new machines with an lxd container) + juju add-machine lxd:4 (starts a new lxd container on machine 4) + juju add-machine --constraints mem=8G (starts a machine with at least 8GB RAM) + juju add-machine ssh:user@10.10.0.3 (manually provisions machine with ssh) + juju add-machine winrm:user@10.10.0.3 (manually provisions machine with winrm) + juju add-machine zone=us-east-1a (start a machine in zone us-east-1a on AWS) + juju add-machine maas2.name (acquire machine maas2.name on MAAS) + **See also:** @@ -394,11 +436,12 @@ information on it. **Examples:** - juju add-model mymodel - juju add-model mymodel us-east-1 - juju add-model mymodel aws/us-east-1 - juju add-model mymodel --config my-config.yaml --config image-stream=daily - juju add-model mymodel --credential credential_name --config authorized-keys="ssh-rsa ..." + juju add-model mymodel + juju add-model mymodel us-east-1 + juju add-model mymodel aws/us-east-1 + juju add-model mymodel --config my-config.yaml --config image-stream=daily + juju add-model mymodel --credential credential_name --config authorized-keys="ssh-rsa ..." + @@ -425,47 +468,38 @@ information on it. **Details:** - Add a relation between 2 local application endpoints or a local endpoint and - a remote application endpoint. Adding a relation between two remote - application endpoints is not supported. Application endpoints can be - identified either by: - - `[:]` + Add a relation between 2 local application endpoints or a local endpoint and a remote application endpoint. + Adding a relation between two remote application endpoints is not supported. + Application endpoints can be identified either by: - where application name supplied without relation will be internally expanded - to be well-formed + [:] + where application name supplied without relation will be internally expanded to be well-formed or - - `.[:]` - - where the application is hosted in another model owned by the current user, - in the same controller + .[:] + where the application is hosted in another model owned by the current user, in the same controller or - - `/.[:]` - - where user/model is another model in the same controller + /.[:] + where user/model is another model in the same controller - For a cross model relation, if the consuming side is behind a firewall - and/or NAT is used for outbound traffic, it is possible to use the --via - option to inform the offering side the source of traffic so that any - required firewall ports may be opened. + For a cross model relation, if the consuming side is behind a firewall and/or NAT is used for outbound traffic, + it is possible to use the --via option to inform the offering side the source of traffic so that any required + firewall ports may be opened. **Examples:** - juju add-relation wordpress mysql - - (where "wordpress" and "mysql" will be internally expanded to "wordpress:db" and "mysql:server" respectively) + $ juju add-relation wordpress mysql + where "wordpress" and "mysql" will be internally expanded to "wordpress:db" and "mysql:server" respectively - juju add-relation wordpress someone/prod.mysql + $ juju add-relation wordpress someone/prod.mysql + where "wordpress" will be internally expanded to "wordpress:db" - (where "wordpress" will be internally expanded to "wordpress:db") + $ juju add-relation wordpress someone/prod.mysql --via 192.168.0.0/16 + + $ juju add-relation wordpress someone/prod.mysql --via 192.168.0.0/16,10.0.0.0/8 - juju add-relation wordpress someone/prod.mysql --via 192.168.0.0/16 - juju add-relation wordpress someone/prod.mysql --via 192.168.0.0/16,10.0.0.0/8 **Aliases:** @@ -533,20 +567,23 @@ information on it. **Examples:** - juju add-ssh-key "ssh-rsa qYfS5LieM79HIOr535ret6xy - AAAAB3NzaC1yc2EAAAADAQA6fgBAAABAQCygc6Rc9XgHdhQqTJ - Wsoj+I3xGrOtk21xYtKijnhkGqItAHmrE5+VH6PY1rVIUXhpTg - pSkJsHLmhE29OhIpt6yr8vQSOChqYfS5LieM79HIOJEgJEzIqC - 52rCYXLvr/BVkd6yr4IoM1vpb/n6u9o8v1a0VUGfc/J6tQAcPR - ExzjZUVsfjj8HdLtcFq4JLYC41miiJtHw4b3qYu7qm3vh4eCiK - 1LqLncXnBCJfjj0pADXaL5OQ9dmD3aCbi8KFyOEs3UumPosgmh - VCAfjjHObWHwNQ/ZU2KrX1/lv/+lBChx2tJliqQpyYMiA3nrtS - jfqQgZfjVF5vz8LESQbGc6+vLcXZ9KQpuYDt joe@ubuntu" + juju add-ssh-key "ssh-rsa qYfS5LieM79HIOr535ret6xy + AAAAB3NzaC1yc2EAAAADAQA6fgBAAABAQCygc6Rc9XgHdhQqTJ + Wsoj+I3xGrOtk21xYtKijnhkGqItAHmrE5+VH6PY1rVIUXhpTg + pSkJsHLmhE29OhIpt6yr8vQSOChqYfS5LieM79HIOJEgJEzIqC + 52rCYXLvr/BVkd6yr4IoM1vpb/n6u9o8v1a0VUGfc/J6tQAcPR + ExzjZUVsfjj8HdLtcFq4JLYC41miiJtHw4b3qYu7qm3vh4eCiK + 1LqLncXnBCJfjj0pADXaL5OQ9dmD3aCbi8KFyOEs3UumPosgmh + VCAfjjHObWHwNQ/ZU2KrX1/lv/+lBChx2tJliqQpyYMiA3nrtS + jfqQgZfjVF5vz8LESQbGc6+vLcXZ9KQpuYDt joe@ubuntu" + For ease of use it is possible to use shell substitution to pass the key to the command: + juju add-ssh-key "$(cat ~/mykey.pub)" + **See also:** [ssh-keys](#ssh-keys) , @@ -608,19 +645,22 @@ information on it. **Examples:** - # Add 3 ebs storage instances for "data" storage to unit u/0: - juju add-storage u/0 data=ebs,1024,3 - or - juju add-storage u/0 data=ebs,3 - or - juju add-storage u/0 data=ebs,,3 - - - # Add 1 storage instances for "data" storage to unit u/0 - # using default model provider pool: - juju add-storage u/0 data=1 - or - juju add-storage u/0 data + Add 3 ebs storage instances for "data" storage to unit u/0: + + juju add-storage u/0 data=ebs,1024,3 + or + juju add-storage u/0 data=ebs,3 + or + juju add-storage u/0 data=ebs,,3 + + + Add 1 storage instances for "data" storage to unit u/0 + using default model provider pool: + + juju add-storage u/0 data=1 + or + juju add-storage u/0 data + @@ -678,7 +718,7 @@ information on it. _--attach-storage (= )_ - Existing storage to attach to the deployed unit + Existing storage to attach to the deployed unit (not available on kubernetes models) _-m, --model (= "")_ @@ -696,59 +736,68 @@ information on it. **Details:** - The add-unit command adds units to an existing application. It is used - to scale out an application for improved performance or availability. + The add-unit is used to scale out an application for improved performance or + availability. + + The usage of this command differs depending on whether it is being used on a + Kubernetes or cloud model. + + Many charms will seamlessly support horizontal scaling while others may need + an additional application support (e.g. a separate load balancer). See the + documentation for specific charms to check how scale-out is supported. + For Kubernetes models the only valid argument is -n, --num-units. + + Anything additional will result in an error. + + Example: + + Add five units of mysql: - Many charms will seamlessly support horizontal scaling while others - may need an additional application support (e.g. a separate load - balancer). See the documentation for specific charms to check how - scale-out is supported. + juju add-unit mysql --num-units 5 + + For cloud models, by default, units are deployed to newly provisioned machines + in accordance with any application or model constraints. - By default, units are deployed to newly provisioned machines in - accordance with any application or model constraints. This command - also supports the placement directive ("--to") for targeting specific - machines or containers, which will bypass application and model + This command also supports the placement directive ("--to") for targeting + specific machines or containers, which will bypass application and model constraints. **Examples:** - Add five units of wordpress on five new machines: + Add five units of mysql on five new machines: - juju add-unit wordpress -n 5 + juju add-unit mysql -n 5 Add a unit of mysql to machine 23 (which already exists): - juju add-unit mysql --to 23 - - Add two units of mysql to machines 3 and 4: - - juju add-unit mysql -n 2 --to 3,4 + juju add-unit mysql --to 23 - Add three units of mysql to machine 7: + Add two units of mysql to existing machines 3 and 4: - juju add-unit mysql -n 3 --to 7,7,7 + juju add-unit mysql -n 2 --to 3,4 Add three units of mysql, one to machine 3 and the others to new machines: - juju add-unit mysql -n 3 --to 7 + juju add-unit mysql -n 3 --to 3 - Add a unit into a new LXD container on machine 7: + Add a unit of mysql into a new LXD container on machine 7: - juju add-unit mysql --to lxd:7 + juju add-unit mysql --to lxd:7 - Add two units into two new LXD containers on machine 7: + Add two units of mysql into two new LXD containers on machine 7: - juju add-unit mysql -n 2 --to lxd:7,lxd:7 + juju add-unit mysql -n 2 --to lxd:7,lxd:7 - Add a unit of mariadb to LXD container number 3 on machine 24: + Add a unit of mysql to LXD container number 3 on machine 24: - juju add-unit mariadb --to 24/lxd/3 + juju add-unit mysql --to 24/lxd/3 - Add a unit of mariadb to LXD container on a new machine: + Add a unit of mysql to LXD container on a new machine: + + juju add-unit mysql --to lxd - juju add-unit mariadb --to lxd **See also:** @@ -791,8 +840,9 @@ information on it. **Examples:** - juju add-user bob - juju add-user --controller mycontroller bob + juju add-user bob + juju add-user --controller mycontroller bob + **See also:** @@ -843,13 +893,19 @@ information on it. **Examples:** - # Displays terms for somePlan revision 1 and prompts for agreement. - juju agree somePlan/1 - # Displays the terms for revision 1 of somePlan, revision 2 of otherPlan, - # and prompts for agreement. - juju agree somePlan/1 otherPlan/2 - # Agrees to the terms without prompting. - juju agree somePlan/1 otherPlan/2 --yes + Displays terms for somePlan revision 1 and prompts for agreement. + + juju agree somePlan/1 + + Displays the terms for revision 1 of somePlan, revision 2 of otherPlan, + and prompts for agreement. + + juju agree somePlan/1 otherPlan/2 + + Agrees to the terms without prompting. + + juju agree somePlan/1 otherPlan/2 --yes + @@ -992,7 +1048,8 @@ information on it. **Examples:** - juju attach-storage postgresql/1 pgdata/0 + juju attach-storage postgresql/1 pgdata/0 + @@ -1039,7 +1096,12 @@ information on it. 1. On Linux, $HOME/.novarc 2. Environment variables OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, - OS_DOMAIN_NAME + + OS_DOMAIN_NAME + LXD + Credentials: + + 1. On Linux, $HOME/.config/lxc/config.yml Example: @@ -1214,8 +1276,8 @@ information on it. Available keys for use with --config can be found here: - https://jujucharms.com/docs/stable/controllers-config - https://jujucharms.com/docs/stable/models-config + https://jujucharms.com/stable/controllers-config + https://jujucharms.com/stable/models-config You can change the default timeout and retry delays used during the bootstrap by changing the following settings in your configuration @@ -1233,12 +1295,12 @@ information on it. Private clouds may need to specify their own custom image metadata and tools/agent. Use '--metadata-source' whose value is a local directory. - By default, the Juju version of the agent binary that is downloaded and - installed on all models for the new controller will be the same as that + By default, the Juju version of the agent binary that is downloaded and + installed on all models for the new controller will be the same as that of the Juju client used to perform the bootstrap. - However, a user can specify a different agent version via '--agent-version' - option to bootstrap command. Juju will use this version for models' agents + However, a user can specify a different agent version via '--agent-version' + option to bootstrap command. Juju will use this version for models' agents as long as the client's version is from the same Juju release series. In other words, a 2.2.1 client can bootstrap any 2.2.x agents but cannot @@ -1252,21 +1314,22 @@ information on it. * 2.3.2 controller by running 'bootstrap --auto-upgrade'. - However, if this client has a copy of codebase, then a local copy of Juju + However, if this client has a copy of codebase, then a local copy of Juju will be built and bootstrapped - 2.3.1.1. **Examples:** - juju bootstrap - juju bootstrap --clouds - juju bootstrap --regions aws - juju bootstrap aws - juju bootstrap aws/us-east-1 - juju bootstrap google joe-us-east1 - juju bootstrap --config=~/config-rs.yaml rackspace joe-syd - juju bootstrap --agent-version=2.2.4 aws joe-us-east-1 - juju bootstrap --config bootstrap-timeout=1200 azure joe-eastus + juju bootstrap + juju bootstrap --clouds + juju bootstrap --regions aws + juju bootstrap aws + juju bootstrap aws/us-east-1 + juju bootstrap google joe-us-east1 + juju bootstrap --config=~/config-rs.yaml rackspace joe-syd + juju bootstrap --agent-version=2.2.4 aws joe-us-east-1 + juju bootstrap --config bootstrap-timeout=1200 azure joe-eastus + **See also:** @@ -1311,10 +1374,13 @@ information on it. **Examples:** - # Sets the budget for the current model to 10. - juju budget 10 - # Moves the budget for the current model to wallet 'personal' and sets the limit to 10. - juju budget personal:10 + Sets the budget for the current model to 10. + + juju budget 10 + Moves the budget for the current model to wallet 'personal' and sets the limit to 10. + + juju budget personal:10 + @@ -1374,12 +1440,18 @@ information on it. **Examples:** - # List all cached images. - juju cached-images - # List cached images for xenial. - juju cached-images --series xenial - # List all cached lxd images for xenial amd64. - juju cached-images --kind lxd --series xenial --arch amd64 + List all cached images. + + juju cached-images + + List cached images for xenial. + + juju cached-images --series xenial + + List all cached lxd images for xenial amd64. + + juju cached-images --kind lxd --series xenial --arch amd64 + **Aliases:** @@ -1461,11 +1533,12 @@ information on it. **Examples:** - juju change-user-password - juju change-user-password bob - juju change-user-password bob --reset - juju change-user-password -c another-known-controller - juju change-user-password bob --controller another-known-controller + juju change-user-password + juju change-user-password bob + juju change-user-password bob --reset + juju change-user-password -c another-known-controller + juju change-user-password bob --controller another-known-controller + **See also:** @@ -1477,21 +1550,18 @@ information on it. ^# charm - **Usage:** ` juju charm [options] ...` + **Usage:** ` juju charm [flags] ...` **Summary:** DEPRECATED: Interact with charms. - **Options:** - - _--description (= false)_ - - - - _-h, --help (= false)_ +Flags: +--description (= false) + Show short description of plugin, if any +-h, --help (= false) + Show help on a command or other topic. - Show help on a command or other topic. **Details:** @@ -1587,19 +1657,31 @@ information on it. **Details:** - Provided information includes 'cloud' (as understood by Juju), cloud - 'type', and cloud 'regions'. + Output includes fundamental properties for each cloud known to the + current Juju client: name, number of regions, default region, type, + and description. - The listing will consist of public clouds and any custom clouds made - available through the `juju add-cloud` command. The former can be updated - via the `juju update-clouds` command. + The default output shows public clouds known to Juju out of the box. - By default, the tabular format is used. + These may change between Juju versions. In addition to these public + clouds, the 'localhost' cloud (local LXD) is also listed. + + This command's default output format is 'tabular'. + + Cloud metadata sometimes changes, e.g. AWS adds a new region. Use the + `update-clouds` command to update the current Juju client accordingly. + Use the `add-cloud` command to add a private cloud to the list of + clouds known to the current Juju client. + Use the `regions` command to list a cloud's regions. Use the + `show-cloud` command to get more detail, such as regions and endpoints. + Further reading: https://docs.jujucharms.com/stable/clouds **Examples:** - juju clouds + juju clouds + juju clouds --format yaml + **See also:** @@ -1691,16 +1773,22 @@ information on it. See `juju status` for application names. + When only one configuration value is desired, the command will ignore --format + option and will output the value unformatted. This is provided to support + scripts where the output of "juju config " + can be used as an input to an expression or a function. + **Examples:** - juju config apache2 - juju config --format=json apache2 - juju config mysql dataset-size - juju config mysql --reset dataset-size,backup_dir - juju config apache2 --file path/to/config.yaml - juju config mysql dataset-size=80% backup_dir=/vol1/mysql/backups - juju config apache2 --model mymodel --file /home/ubuntu/mysql.yaml + juju config apache2 + juju config --format=json apache2 + juju config mysql dataset-size + juju config mysql --reset dataset-size,backup_dir + juju config apache2 --file path/to/config.yaml + juju config mysql dataset-size=80% backup_dir=/vol1/mysql/backups + juju config apache2 --model mymodel --file /home/ubuntu/mysql.yaml + **See also:** @@ -1740,9 +1828,10 @@ information on it. **Examples:** - $ juju consume othermodel.mysql - $ juju consume owner/othermodel.mysql - $ juju consume anothercontroller:owner/othermodel.mysql + $ juju consume othermodel.mysql + $ juju consume owner/othermodel.mysql + $ juju consume anothercontroller:owner/othermodel.mysql + **See also:** @@ -1793,16 +1882,17 @@ information on it. Available keys and values can be found here: - https://jujucharms.com/docs/stable/controllers-config + https://jujucharms.com/stable/controllers-config **Examples:** - juju controller-config - juju controller-config api-port - juju controller-config -c mycontroller - juju controller-config auditing-enabled=true audit-log-max-backups=5 - juju controller-config auditing-enabled=true path/to/file.yaml - juju controller-config path/to/file.yaml + juju controller-config + juju controller-config api-port + juju controller-config -c mycontroller + juju controller-config auditing-enabled=true audit-log-max-backups=5 + juju controller-config auditing-enabled=true path/to/file.yaml + juju controller-config path/to/file.yaml + **See also:** @@ -1848,8 +1938,9 @@ information on it. **Examples:** - juju controllers - juju controllers --format json --output ~/tmp/controllers.json + juju controllers + juju controllers --format json --output ~/tmp/controllers.json + **See also:** @@ -1897,11 +1988,27 @@ information on it. **Details:** - create-backup requests that Juju creates a backup of its state and prints the + This command requests that Juju creates a backup of its state and prints the backup's unique ID. You may provide a note to associate with the backup. - The backup archive and associated metadata are stored remotely by Juju, but - will also be copied locally unless --no-download is supplied. To access the - remote backups, see 'juju download-backup'. + By default, the backup archive and associated metadata are downloaded + without keeping a copy remotely on the controller. + + Use --no-download to avoid getting a local copy of the backup downloaded + at the end of the backup process. + + Use --keep-copy option to store a copy of backup remotely on the controller. + Use --verbose to see extra information about backup. + + To access remote backups stored on the controller, see 'juju download-backup'. + + **Examples:** + + juju create-backup + juju create-backup --no-download + juju create-backup --no-download --keep-copy=false // ignores --keep-copy + juju create-backup --keep-copy + juju create-backup --verbose + **See also:** @@ -1983,8 +2090,10 @@ information on it. **Examples:** - # Creates a wallet named 'qa' with a limit of 42. - juju create-wallet qa 42 + Creates a wallet named 'qa' with a limit of 42. + + juju create-wallet qa 42 + @@ -2047,9 +2156,10 @@ information on it. **Examples:** - juju credentials - juju credentials aws - juju credentials --format yaml --show-secrets + juju credentials + juju credentials aws + juju credentials --format yaml --show-secrets + **See also:** @@ -2225,27 +2335,39 @@ information on it. Exclude all machine 0 messages; show a maximum of 100 lines; and continue to append filtered messages: - juju debug-log --exclude machine-0 --lines 100 + + juju debug-log --exclude machine-0 --lines 100 + Include only unit mysql/0 messages; show a maximum of 50 lines; and then exit: - juju debug-log -T --include unit-mysql-0 --lines 50 + + juju debug-log -T --include unit-mysql-0 --lines 50 + Show all messages from unit apache2/3 or machine 1 and then exit: - juju debug-log -T --replay --include unit-apache2-3 --include machine-1 + + juju debug-log -T --replay --include unit-apache2-3 --include machine-1 + Show all juju.worker.uniter logging module messages that are also unit wordpress/0 messages, and then show any new log messages which match the filter: - juju debug-log --replay - --include-module juju.worker.uniter \ - --include unit-wordpress-0 + + juju debug-log --replay + --include-module juju.worker.uniter \ + --include unit-wordpress-0 + Show all messages from the juju.worker.uniter module, except those sent from machine-3 or machine-4, and then stop: - juju debug-log --replay --no-tail - --include-module juju.worker.uniter \ - --exclude machine-3 \ - --exclude machine-4 + + juju debug-log --replay --no-tail + --include-module juju.worker.uniter \ + --exclude machine-3 \ + --exclude machine-4 + To see all WARNING and ERROR messages and then continue showing any new WARNING and ERROR messages as they are logged: - juju debug-log --replay --level WARNING + + juju debug-log --replay --level WARNING + **See also:** @@ -2261,7 +2383,7 @@ information on it. **Summary:** - Deploy a new application or bundle. + Deploys a new application or bundle. **Options:** @@ -2271,7 +2393,7 @@ information on it. _--attach-storage (= )_ - Existing storage to attach to the deployed unit + Existing storage to attach to the deployed unit (not available on kubernetes models) _--bind (= "")_ @@ -2289,17 +2411,21 @@ information on it. Set application constraints + _--device (= )_ + + Charm device constraints + _--dry-run (= false)_ Just show what the bundle deploy would do _--force (= false)_ - Allow a charm to be deployed to a machine running an unsupported series + Allow a charm to be deployed which bypasses checks such as supported series or LXD profile allow list _--increase-budget (= 0)_ - Increase model budget allocation by this amount + increase model budget allocation by this amount _-m, --model (= "")_ @@ -2319,7 +2445,7 @@ information on it. _--plan (= "")_ - Plan to deploy charm under + plan to deploy charm under _--resource (= )_ @@ -2345,202 +2471,231 @@ information on it. **Details:** - `` can be a charm/bundle URL, or an unambiguously condensed - form of it; assuming a current series of "trusty", the following forms will be - accepted: - - mediawiki: - name: my media wiki - admins: me:pwdOne - debug: true + A charm can be referred to by its simple name and a series can optionally be + specified: - For `cs:trusty/mysql`: - - 'mysql' or - 'trusty/mysql' + juju deploy postgresql + juju deploy xenial/postgresql + juju deploy cs:postgresql + juju deploy cs:xenial/postgresql + juju deploy postgresql --series xenial - For `cs:~user/trusty/mysql`: + All the above deployments use remote charms found in the Charm Store (denoted + by 'cs') and therefore also make use of "charm URLs". + + A versioned charm URL will be expanded as expected. For example, 'mysql-56' + becomes 'cs:xenial/mysql-56'. + + A local charm may be deployed by giving the path to its directory: + + juju deploy /path/to/charm + juju deploy /path/to/charm --series xenial - '~user/mysql' + You will need to be explicit if there is an ambiguity between a local and a + remote charm: + + juju deploy ./pig + juju deploy cs:pig - For `cs:bundle/mediawiki-single`: + An error is emitted if the determined series is not supported by the charm. Use + the '--force' option to override this check: + + juju deploy charm --series xenial --force - 'mediawiki-single' or - 'bundle/mediawiki-single' + A bundle can be expressed similarly to a charm, but not by series: + juju deploy mediawiki-single + juju deploy bundle/mediawiki-single + juju deploy cs:bundle/mediawiki-single - The current series for charms is determined first by the 'default-series' model - setting, followed by the preferred series for the charm in the charm store. - In these cases, a versioned charm URL will be expanded as expected (for - example, mysql-33 becomes cs:precise/mysql-33). - - Charms may also be deployed from a user specified path. In this case, the path - to the charm is specified along with an optional series. - - juju deploy /path/to/charm --series trusty + A local bundle may be deployed by specifying the path to its YAML file: + juju deploy /path/to/bundle.yaml - If '--series' is not specified, the charm's default series is used. The default - series for a charm is the first one specified in the charm metadata. If the - specified series is not supported by the charm, this results in an error, - unless '--force' is used. + The final charm/machine series is determined using an order of precedence (most + preferred to least): - juju deploy /path/to/charm --series wily --force + - the '--series' command option + - the series stated in the charm URL + - for a bundle, the series stated in each charm URL (in the bundle file) + - for a bundle, the series given at the top level (in the bundle file) + - the 'default-series' model key + - the top-most series specified in the charm's metadata file + (this sets the charm's 'preferred series' in the Charm Store) - Local bundles are specified with a direct path to a bundle.yaml file. - For example: + An 'application name' provides an alternate name for the application. It works + only for charms; it is silently ignored for bundles (although the same can be + done at the bundle file level). Such a name must consist only of lower-case + letters (a-z), numbers (0-9), and single hyphens (-). The name must begin with + a letter and not have a group of all numbers follow a hyphen: - juju deploy /path/to/bundle/openstack/bundle.yaml + Valid: myappname, custom-app, app2-scat-23skidoo + Invalid: myAppName, custom--app, app2-scat-23, areacode-555-info - If an 'application name' is not provided, the application name used is the - 'charm or bundle' name. A user-supplied 'application name' must consist only of - lower-case letters (a-z), numbers (0-9), and single hyphens (-). The name must - begin with a letter and not have a group of all numbers follow a hyphen. For - instance: + Use the '--constraints' option to specify hardware requirements for new machines. + These become the application's default constraints (i.e. they are used if the + application is later scaled out with the `add-unit` command). To overcome this + behaviour use the `set-constraints` command to change the application's default + constraints or add a machine (`add-machine`) with a certain constraint and then + target that machine with `add-unit` by using the '--to' option. - Valid: myappname, custom-app, app2-scat-23skidoo - Invalid: myAppName, custom--app, app2-scat-23, areacode-555-info + Use the '--device' option to specify GPU device requirements (with Kubernetes). + The below format is used for this option's value, where the 'label' is named in + the charm metadata file: - Constraints can be specified by specifying the '--constraints' option. If the - application is later scaled out with `juju add-unit`, provisioned machines - will use the same constraints (unless changed by `juju set-constraints`). - Application configuration values can be specified using '--config' option. This - option accepts either a path to a yaml-formatted file or a key=value pair. - Configuration file provided should be in format +