diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt index 23fc743..be8059b 100644 --- a/.custom_wordlist.txt +++ b/.custom_wordlist.txt @@ -5,8 +5,6 @@ APIs auditability aws balancer -Candid -Candid's certbot Charmhub CLI diff --git a/explanation/jaas_security_scope.rst b/explanation/jaas_security_scope.rst index cee76ae..21f8525 100644 --- a/explanation/jaas_security_scope.rst +++ b/explanation/jaas_security_scope.rst @@ -1,9 +1,6 @@ JAAS: Security Scope ======================== -.. warning:: - This document has not been updated for JIMM.V2. - The scope of JAAS' security covers multiple aspects, including: Secure Communication @@ -18,10 +15,10 @@ additionally acting as the IdP (Identity Provider) for said tokens. Access control and authentication --------------------------------- JAAS provides an abstraction layer of access control on top of Juju. JAAS does this by backing its users -with an IdP (Identity Provider), this particular IdP is called Candid which handles the authentication -for JIMM (Juju Intelligent Model Manager, the back-end to JAAS). Furthermore, JAAS is capable of many -authentication and authorisation types, ranging from users to agents. For authorisation, JAAS provides -this by means of tags and ReBAC (Relation Based Access Control). +with an IdP (Identity Provider). Various identity providers can be used for this purpose (e.g. Google or Microsoft). +We recommend the `Canonical identity platform`_ as the preferred IdP for JAAS. The IdP will handle user +authentication on behalf of JAAS using OAuth 2.0 and OIDC. For authorisation, JAAS provides this by means +of tags and ReBAC (Relation-Based Access Control). Auditing and logging -------------------- diff --git a/explanation/jaas_tags.rst b/explanation/jaas_tags.rst index 9e38d32..7755ca5 100644 --- a/explanation/jaas_tags.rst +++ b/explanation/jaas_tags.rst @@ -18,8 +18,7 @@ A user tag has the following format: user- -where ``username`` uniquely identifies a user including the domain specified -by Candid. +where ``username`` uniquely identifies a user including the domain. Group ----- diff --git a/how-to/deploy_jimm.rst b/how-to/deploy_jimm.rst deleted file mode 100644 index 4eaa720..0000000 --- a/how-to/deploy_jimm.rst +++ /dev/null @@ -1,45 +0,0 @@ -JAAS: Deploy JIMM -================= - -.. warning:: - This document has not been updated for JIMM.V2. - -Introduction ------------- - -In this how-to we will be deploying JIMM. JIMM - Juju Intelligent Model Manager provides -the ability to manage multiple Juju models from a single point. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. - -Deploy JIMM ------------ - -1. Bootstrap a controller: juju bootstrap aws -2. Download the JIMM bundle from `here `_ -3. Extract the file: ``tar xvf jimm.tar.xz`` -4. Move to the JIMM folder: ``cd jimm`` -5. Deploy the bundle: ``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` -6. Once the bundle has been deployed, get the public IP of the ``haproxy/0`` unit: ``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` -7. Go to the `Route 53 dashboard `_ -8. Add an **A** record for the deployed JIMM (e.g. ``jimm.canonical.example.com``) with the IP obtained in step 6. -9. Obtain a valid certificate for the deployed candid by running: ``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains= email= plugin=dns-route53`` -10. Let JIMM know its DNS name (replace ``jimm.canonical.example.com`` with the DNS name you set up in step 8): ``juju config jimm dns-name=jimm.canonical.stimec.net`` -11. Configure the URL of the Candid JIMM should use. For this tutorial we will use the official Candid: ``juju config jimm candid-url=https://api.jujucharms.com/identity`` -12. Add yourself to the list of JIMM administrators: ``juju config jimm controller-admins=@external`` - -Following these steps you have deployed JIMM that uses the Canonical Candid service. - -To verify that JIMM is working correctly you can try: -``juju login candid.canonical.example.com`` - -Once you have logged in with the Canonical Candid service you should see candid.canonical.example.com in the list of controller if you run: -``juju controllers`` diff --git a/how-to/deploy_jimm_k8s.rst b/how-to/deploy_jimm_k8s.rst deleted file mode 100644 index 7934452..0000000 --- a/how-to/deploy_jimm_k8s.rst +++ /dev/null @@ -1,259 +0,0 @@ -JAAS: Deploy JIMM on K8S -======================== - -.. warning:: - This document has not been updated for JIMM.V3. - -Introduction ------------- - -In this how-to we will be deploying JIMM on Kubernetes. JIMM - Juju Intelligent Model Manager provides the ability to manage multiple Juju models from a single point. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) -- AWS credentials -- Basic knowledge of juju -- A subdomain registered with Route 53. To learn how to set that up, please follow :doc:`route53`. -- Access to a Kubernetes cluster -- Access to a PostgreSQL database - -Deploy a Kubernetes cluster ---------------------------- - - -In case you do not already have access to a Kubernetes cluster, you can deploy one on AWS. Start by bootstrapping a new controller in AWS: - -``juju bootstrap aws k8s-controller`` - -and then deploy the ``kubernetes-core`` bundle: - -``juju deploy kubernetes-core`` - -and the aws-integrator charm: - -``juju deploy aws-integrator`` - -which simplifies working with charmed Kubernetes on AWS. -Use the following commands to configure and relate aws-integrator to various applications: - -.. code:: - - juju trust aws-integrator - juju relate aws-integrator kubernetes-control-plane - juju relate aws-integrator kubernetes-worker - -Once all applications settle down and start fetch the config file that will let you use ``kubectl``: - -``juju scp kubernetes-control-plane/0:config ~/.kube/config`` - -Deploy JIMM ------------ - -Once you have access to a K8s cluster, you can verify it by running: - -``kubectl get nodes`` - -and if that works add the Kubernetes cluster as a cloud to your juju client: - -``juju add-k8s myk8s`` - -We can the bootstrap a new controller in the added k8s cluster by running: - -``juju bootstrap myk8s infrastructure`` - -and when this process finishes we can add a new model for JIMM: - -``juju add-model JIMM`` - -Now we can deploy the JIMM into the newly created model: - -``juju deploy jimm-k8s --channel edge`` - -As Juju does not currently support exposing an application on a k8s cloud, we need to also deploy ``nginx-ingress-integrator`` charm. Run: - -.. code:: - - juju deploy nginx-ingress-integrator ingress - juju trust ingress --scope=cluster - juju relate ingress jimm-k8s - -Once deployed go to the management console of your domain and create an A record for the deployed JIMM (e.g. ``jimm.canonical.example.com``) with the IP of k8s worker nodes. - -Configure JIMM --------------- - -Once deployed we need to configure JIMM. Run the following commands: - -.. code:: - - juju config jimm-k8s dsn= - juju config jimm-k8s uuid= - juju config jimm-k8s candid-url=https://api.jujucharms.com/identity - juju config jimm-k8s dns-name=jimm. - - -Next we also need to configure ingress. Usually the Kubernetes cluster operator will set up a Kubernetes secret for you containing a certificate and key for JIMM's FQDN (in case you need a certificate look at the next section) and give you the secret name. All you need to do next is: - -``juju config ingress tls-secret-name=`` - -and the ingress charm will get certificates from the Kubernetes secret and set up TLS for you. -Now you can log in to the deployed JIMM -juju login ``jimm.`` - -Appendix --------- - -Don't have a PostgreSQL database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In case you do not have access to a PostgreSQL database you can use Amazon's RDS to create one. Navigate to the RDS console and select "Create database". Under "Engine type" select "PostgreSQL", specify "Master username" and "Master password". Also make sure to select "Public access" as "Yes". You can customise all other options to your preference. Once the database is created, navigate to the database's dashboard. There you will see the "Endpoint" and "Port" strings, which you will need to connect to the database. Use the following command to configure JIMM: :none:`wokeignore:rule=master,` - - ``juju config jimm-k8s dns=postgres://:@:/`` :none:`wokeignore:rule=master,` - -Don't have certificates -~~~~~~~~~~~~~~~~~~~~~~~ - -In case the cluster operator did not set up a Kubernetes secret for you containing certificate and key for JIMM's FQDN, you can use Let’s Encrypt and cert-manager to get the certificate. -First, you will need to install helm: - -``sudo snap install helm`` - -Then run the following commands to deploy cert-manager: - -.. code:: - - helm repo add jetstack https://charts.jetstack.io - helm repo update - helm install certmgr jetstack/cert-manager - --set installCRDs=true \ - --version v1.9.1 \ - --namespace cert-manager \ - --create-namespace - -Since the production Let’s Encrypt servers do some fancy rate limiting and we don’t want to exceed the limit, we will first test our setup with the staging server. -Create a file ``stg-issuer.yaml`` with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: - name: letsencrypt-staging - spec: - acme: - # The ACME server URL - server: https://acme-staging-v02.api.letsencrypt.org/directory - # Email address used for ACME registration - email: - # Name of a secret used to store the ACME account private key - privateKeySecretRef: - name: letsencrypt-staging - # Enable the HTTP-01 challenge provider - solvers: - - http01: - ingress: - class: nginx - -and run: - -``kubectl apply -n jimm -f stg-issuer.yaml`` - -which will create a certificate issuer in JIMM's namespace. -The create ``stg-certs.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: jimm-stg-cert #name of this object - namespace: jimm #same namespace as - spec: - dnsNames: - - jimm.canonical.stimec.net - secretName: letsencrypt-stg-certs - issuerRef: - name: letsencrypt-staging - kind: Issuer - -and run: - -``kubectl apply -n jimm -f stg-certs.yaml`` - -This should create a certificate and key using the staging issuer. Inspect the created certificate by running: - -``kubectl describe certificate -n jimm jimm-stg-cert`` - -and: - -``kubectl describe secret letsencrypt-stg-certs -n jimm`` - -which will show a Kubernetes secret and in its data you should see a stored ``tls.crt`` and ``tls.key``. -If this all worked (and i have no doubt it did :) ), then we can proceed by creating a production issuer. Create a ``prod-issuer.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: - name: letsencrypt-prod - spec: - acme: - # The ACME server URL - server: https://acme-v02.api.letsencrypt.org/directory - # Email address used for ACME registration - email: ales.stimec@canonical.com - # Name of a secret used to store the ACME account private key - privateKeySecretRef: - name: letsencrypt-prod - # Enable the HTTP-01 challenge provider - solvers: - - http01: - ingress: - class: nginx - -and run: - -``kubectl apply -n jimm -f prod-issuer.yaml`` - -Then create a ``prod-certs.yaml`` file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: jimm-cert #name of this object - namespace: jimm #same namespace as - spec: - dnsNames: - - jimm.canonical.stimec.net - secretName: letsencrypt-certs - issuerRef: - name: letsencrypt-prod - kind: Issuer - -and run: - -``kubectl apply -n jimm -f prod-certs.yaml`` - -This will create a ``letsencrypt-certs`` secrets for you, which you can inspect by running: - -``kubectl describe secret letsencrypt-certs -n jimm`` - -which will show the created secret and in its data you should see a stored ``tls.crt`` and ``tls.key``. - -To see the certificate data run: - -``kubectl describe certificate -n jimm jimm-cert`` - - -Once you have the production certificate, you can configure the ingress application by running: - -``juju config ingress tls-secret-name=letsencrypt-certs`` - - diff --git a/how-to/index.rst b/how-to/index.rst index a14b9c8..2635439 100644 --- a/how-to/index.rst +++ b/how-to/index.rst @@ -3,18 +3,6 @@ How-to guides These how-to guides cover key operations and processes in JAAS. -JIMM Deployment ---------------- - -Here are instructions on how to deploy JIMM. - -.. toctree:: - :maxdepth: 1 - - Deploy JIMM - Deploy JIMM on K8S - - JIMM Configuration ------------------ @@ -27,7 +15,6 @@ After JIMM has been deployed, you need to configure it with your Juju operated c Add a controller to JIMM Migrate models to JAAS Migrate models internally - Set up Route53 Terraform --------- diff --git a/how-to/route53.rst b/how-to/route53.rst deleted file mode 100644 index dd8fd9e..0000000 --- a/how-to/route53.rst +++ /dev/null @@ -1,106 +0,0 @@ -JAAS: Setting up Route53 -======================== - -Introduction ------------- - - -In this document will we will show you how to use Route53 to host a subdomain of the -domain you already own and how to use the certbot charm to obtain a valid certificate. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- A valid registered domain (regardless of the registrar) - -- AWS credentials - -- Basic knowledge of juju - -Creating a hosted zone for the subdomain ----------------------------------------- - -In this tutorial we will assume that you have registered the example.com domain and by -following the steps below you will register a new hosted zone with Route 53 for a -canonical.example.com subdomain. - -1. Go to the Route 53 dashboard. -2. In the navigation pane, choose **Hosted zones**. -3. Choose **Create hosted zone**. -4. Enter the name of the subdomain (example: canonical.example.com) -5. For **Type**, choose **Public hosted zone**. -6. Choose **Created hosted zone**. -7. Route 53 will automatically assign four name servers to the newly created zone. To start using the hosted zone for the subdomain you must create a new name server (NS) record in for the domain (example.com): the name of the NS record must be the same as the name of the subdomain (from the example above: canonical.example.com) and for the value set the names of the name servers assigned to your hosted zone by Route 53. - -Now you have registered the canonical.example.com subdomain as a public hosted zone with Route 53. Record the Hosted zone ID, which you will need in the next step. - -Obtain credentials ------------------- - -In order to be able to use certbot or any other tool that uses programmatic access to obtain valid certificates for your hosts, you will need to create a user and give it rights to use the created hosted zone. - -1. Go to `IAM Console `_. -2. Choose **Users** and then choose **Add users**. -3. Type the name for the new user. -4. Select **Access key - Programmatic access** under the **Select AWS credential type**. -5. In the next step choose **Attach existing policies directly**. -6. Choose **Create policy**. -7. Choose **JSON**. -8. Paste the following: - -.. code:: json - - { - "Version": "2012-10-17", - "Id": "certbot-dns-route53 sample policy", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "route53:ListHostedZones", - "route53:GetChange" - ], - "Resource": [ - "*" - ] - }, - { - "Effect": "Allow", - "Action": [ - "route53:ChangeResourceRecordSets" - ], - "Resource": [ - "arn:aws:route53:::hostedzone/" - ] - } - ] - } - -9. Replace the field **** with the hosted zone ID you noted down previously. -10. Type in the **Name** (e.g. route53_access_policy) for the policy and choose **Create policy**. -11. When the policy is created, return to the user creation process. Choose the created policy for the user, review information and choose **Create user**. -12. Copy the **Access key ID** and **Secret access key** credentials. - -Using Certbot to obtain certificates ------------------------------------- - -1. Bootstrap a juju controller (in ``aws``, ``azure`` or ``gce``) -2. Deploy HAProxy -3. Deploy certbot -4. Add relation between ``haproxy`` and ``certbot`` by running: ``juju relate haproxy certbot`` -5. Set the **combined-path** configuration option to the default path for ``haproxy`` by running: ``juju config certbot combined-path=/var/lib/haproxy/default.pem`` -6. Wait for the deploy -7. Check which unit of ``haproxy`` and ``certbot`` has been deployed. In the following steps we assume that these are ``haproxy/0`` and ``certbot/0`` units. Please replace those with appropriate values for your deployment in the following steps. -8. Run the following command to get the public IP of the ``haproxy`` unit: ``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]`` -9. Go to the Route 53 dashboard -10. Choose **Hosted zone** and then the zone you created. -11. Choose **Create Record** -12. In the **Record name** enter the desired DNS name (e.g. demo) and in the value paste the public IP address of the ``haproxy`` unit, then choose **Create records**. -13. Run action on the certbot unit to obtain the certificate: ``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains= email= plugin=dns-route53`` - -The result of this should be a deployed ``haproxy`` with a valid certificate. In case of -errors, please re-check the configuration of your domain’s NS entries at the registrar’s -page and on Route 53. - diff --git a/how-to/use_terraform.rst b/how-to/use_terraform.rst index 5bce180..888c40e 100644 --- a/how-to/use_terraform.rst +++ b/how-to/use_terraform.rst @@ -13,11 +13,11 @@ For this how-to you will need the following: - An identity provider that can be used to create OAuth2.0 client credentials. - Client credentials (``client_id`` and ``client_secret``) generated by the above identity provider. -- A deployed JIMM configured to trust the identity provider. For instructions on - how to deploy JIMM read :doc:`deploy_jimm`. -- A Juju 3.5 controller added to JIMM that can be used to control your chosen cloud. For instructions +- A deployed JAAS configured to trust the identity provider. For instructions on + how to deploy JIMM read :doc:`../tutorial/deploy_jaas_microk8s`. +- A Juju controller added to JIMM that can be used to control your chosen cloud. For instructions on how to add one read :doc:`add_controller`. -- A Juju 3.5 client. +- A Juju client. - Cloud credentials for the chosen cloud (see `here `_). - Basic knowledge of Terraform, Juju Terraform provider and Juju. diff --git a/reuse/links.txt b/reuse/links.txt index e3219d2..0a7b99e 100644 --- a/reuse/links.txt +++ b/reuse/links.txt @@ -1,2 +1,2 @@ .. _Canonical website: https://canonical.com/ -.. _Candid: https://github.com/canonical/candid +.. _Canonical identity platform: https://charmhub.io/topics/canonical-identity-platform diff --git a/tutorial/group_management.rst b/tutorial/group_management.rst index b1ad4ac..032d2ad 100644 --- a/tutorial/group_management.rst +++ b/tutorial/group_management.rst @@ -22,12 +22,11 @@ For this tutorial you will need the following: Group management ---------------- -For this part of the tutorial we will assume your Candid has been configured -to contain the following users: +For this part of the tutorial we will assume the following users exist in an organisation: -- ``alice`` -- ``adam`` -- ``eve`` +- ``alice@canonical.com`` +- ``adam@canonical.com`` +- ``eve@canonical.com`` Next, let us create three groups for these users. Run: @@ -43,11 +42,11 @@ To add users to groups, let's run: .. code:: console - jimmctl auth add relation user-alice member group-A - jimmctl auth add relation user-adam member group-B - jimmctl auth add relation user-eve member group-C + jimmctl auth add relation user-alice@canonical.com member group-A + jimmctl auth add relation user-adam@canonical.com member group-B + jimmctl auth add relation user-eve@canonical.com member group-C -which will add ``alice`` to group ``A``, ``adam`` to group ``B`` and ``eve`` to group ``C``. +which will add Alice to group ``A``, Adam to group ``B`` and Eve to group ``C``. You will notice that we refer to user and group by their *JAAS tags* (for explanation see :doc:`../explanation/jaas_tags`). @@ -110,19 +109,19 @@ explanation see :doc:`../explanation/jaas_tags`). For this tutorial we will assume: - that you have followed the previous part of the tutorial and have - - three users ``alice``, ``adam`` and ``eve`` + - three users ``alice@canonical.com``, ``adam@canonical.com`` and ``eve@canonical.com`` - two groups ``A`` and ``B`` set up during part one of this tutorial - that you have added controller ``test-ctl-1`` to JIMM - that you have added a model ``test-model-1`` on the same controller - that you have deployed PostgreSQL in this model and created and application offer names ``postgresql-db`` -First let us make user ``eve`` an administrator of controller ``test-ctl-1``. Since -``eve`` is not member of any group, we will add a direct relation between the +First let us make user ``eve@canonical.com`` an administrator of controller ``test-ctl-1``. Since +``eve@canonical.com`` is not member of any group, we will add a direct relation between the user and the controller by running: .. code:: console - jimmctl auth relation add user-eve administrator controller-test-ctl-1 + jimmctl auth relation add user-eve@canonical.com administrator controller-test-ctl-1 Now let us make group ``A`` writer on the ``test-model-1`` model. Having write access to a model means users are able to deploy applications in the model and @@ -140,29 +139,29 @@ application offer by running: jimmctl auth relation add group-B#members consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db -Now let us check if ``adam`` has consume access to the application offer +Now let us check if ``adam@canonical.com`` has consume access to the application offer by running: .. code:: console - jimmctl auth relation check user-adam consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db + jimmctl auth relation check user-adam@canonical.com consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db -We should get a positive answer since ``adam`` is member of group ``B`` and +We should get a positive answer since ``adam@canonical.com`` is member of group ``B`` and we have granted members of group ``B`` consume access to the application offer. To remove group ``B``'s access to the application offer we can run: .. code:: console - jimmctl auth relation remove user-adam consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db + jimmctl auth relation remove user-adam@canonical.com consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db Running: .. code:: console - jimmctl auth relation check user-adam consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db + jimmctl auth relation check user-adam@canonical.com consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db -we will see user ``adam`` no longer has access to the application offer. +we will see user ``adam@canonical.com`` no longer has access to the application offer. Conclusion ---------- diff --git a/tutorial/index.rst b/tutorial/index.rst index adba9f9..c72e8e6 100644 --- a/tutorial/index.rst +++ b/tutorial/index.rst @@ -6,6 +6,5 @@ This is a collection of tutorials covering JAAS. .. toctree:: :maxdepth: 1 - JAAS Basics - Group and access management Deploy JAAS on MicroK8s + Group and access management diff --git a/tutorial/jaas_basics.rst b/tutorial/jaas_basics.rst deleted file mode 100644 index 0a3012e..0000000 --- a/tutorial/jaas_basics.rst +++ /dev/null @@ -1,393 +0,0 @@ -JAAS Basics -=========== - -.. warning:: - This document has not been updated to JIMM.V3. - -Introduction ------------- - -JAAS provides a single location to manage your Juju infrastructure by using the Dashboard or using -the Juju CLI commands to create a high-level overview and the ability to drill-in to the details -when you need it. - -JAAS is composed of the following components: - -- Candid - macaroon-based authentication server, which is required so that all other components are able to agree who a particular user is, -- JIMM - Juju Intelligent Model Manager, which acts as a single point of contact for multiple Juju controllers -- Multiple Juju controllers, each controlling models in specific clouds or cloud regions. - -.. image:: images/jaas_image2.png - -In this tutorial we will show you how to deploy all components of JAAS and how to use it to deploy -a workload. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- Have valid AWS credentials you can use -- Have basic knowledge of Juju and are able to use the Juju CLI -- Have AWS credentials Juju can use to deploy in EC2 (see instructions here) -- Own a domain name (e.g. domain.com) -- Have set up subdomain (canonical.domain.com) that is managed by Route 53 (see :doc:`../how-to/route53`). Please replace canonical.domain.com in the rest of this tutorial with the actual subdomain you have set up with Route 53. - -Deploy ------- - -We will be deploying all the components of JAAS in AWS since you already have credentials that -allow Juju to deploy workloads in AWS. - -First, let’s bootstrap a Juju controller in AWS: - -``juju bootstrap aws/eu-central-1 infrastructure`` - -This will create a controller called infrastructure that will control the models into which we -will deploy Candid and JIMM. The process might take a while. - -Candid ------- - -The first component we need to deploy is Candid, so let’s begin by creating a model for Candid: - -``juju add-model candid`` - -To deploy Candid please download `this `__ tarball, -which contains everything you will need. - -Extract the tarball: - -``tar xvf candid_v1.11.0.tar.xz`` - -Now you can move to the extracted candid folder: - -``cd candid`` - -and deploy the bundle. We will be using certbot to obtain valid certificates so we can use the -following command: - -``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -and wait for the deployment to finish. You can observe the deployment status by running: - -``juju status –watch 5s –color`` - -Once the deployment is finished, you will see the certbot and HAProxy units are in an error state. -This is because we still need to obtain a valid certificate for Candid. First we will need to get -the public IP of the ``haproxy/0`` unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -Now you will need to go to the `Route 53 dashboard `_, -navigate to the hosted zone for the canonical.domain.com subdomain and select `Create record`. We -will add an **A** record for candid.canonical.domain.com with the value of the IP of the ``haproxy/0`` -unit we obtained in the previous step. - -To obtain a valid certificate for Candid we will use an action of the certbot charm. Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=candid.canonical.domain.com email= plugin=dns-route53`` - -It might take a while (5 minutes+ is normal) to get the certificate, but once complete: - -``juju status`` - -should show all units in an operational state. - -Next we need to configure Candid. First we set the location configuration parameter: - -``juju config candid location=https://candid.canonical.domain.com`` - -which will tell Candid which DNS it is running on. - -Now all that is left is to set up the identity providers. In this tutorial we will set up a static -identity provider with hard-coded usernames and passwords: - -.. code:: console - - juju config candid identity-providers='- type: static - name: static - description: Default identity provider - users: - user1: - name: User One - email: user1 - password: s3cre7Pa55w0rd1 - groups: - - group1 - user2: - name: User Two - email: user2 - password: s3cre7Pa55w0rd2 - groups: - - group1' - -As you can see we set up Candid to know about two users: user1 and user2 with corresponding -passwords ``s3cre7Pa55w0rd1`` and ``s3cre7Pa55w0rd2``, which you will use to log in. - -Now we have deployed Candid and we can verify if it is working by opening a browser and going to -``https://candid.canonical.domain.com/login`` and try logging in as either user1 or user2. - -JIMM ----- - -Next we will be deploying JIMM, which will allow us to control multiple Juju controllers from a -single point. - -Let’s add a new Juju model for JIMM: - -``juju add-model jimm`` - -To deploy JIMM please download `this `__ tarball and extract it: - -``tar xvf jimm.tar.xz`` - -and move to the extracted JIMM folder: - -``cd jimm`` - -We will be using certbot to obtain valid certificates so we can again use the following command: - -``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -and wait for the deployment to finish. You can observe the deployment status by running: - -``juju status -watch 2s`` - - -Once the deployment is finished you will see that we have deployed 2 JIMM units, 2 PostgreSQL units -and one HAProxy unit. The HAProxy will act as a load balancer redirecting clients to one of the -deployed JIMM units and both JIMM units will connect to the deployed PostgreSQL cluster. We have -also deployed the ntp charm which will make sure the clocks on all units are synchronised and the -certbot charm, which is related to the HAProxy unit and we will use the certbot charm to obtain -valid certificates. - -For now, you will see the certbot and HAProxy units are in an error state. This is because we -still need to obtain a valid certificate for JIMM. First we will need to get the public IP of -the ``haproxy/0`` unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - -Now you will need to go to the `Route 53 dashboard `_, -navigate to the hosted zone for the canonical.domain.com subdomain and select `Create record`. -We will add an **A** record for ``jimm.canonical.domain.com`` with the value of the IP of the -``haproxy/0`` unit we obtained in the previous step. - -To obtain a valid certificate for JIMM we will use an action of the certbot charm. Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=jimm.canonical.domain.com email= plugin=dns-route53`` - -It might take a while to get the certificate, but once complete: - -``juju status`` - -should show all units in an operational state. - -Now we need to configure JIMM to use the Candid we deployed: - -``juju config jimm candid-url=https://candid.canonical.domain.com`` - -And configure JIMM to use the DNS name we set up: - -``juju config jimm dns-name=jimm.canonical.domain.com`` - -Then add user1 as JIMM administrator: - -``juju config jimm controller-admins=user1`` - -We also need to give JIMM a new controller UUID, which it will use to identify itself against -Juju clients. We can generate a random UUID, but for this tutorial we can use: - -``juju config jimm uuid=d55701bf-04e4-4c67-b3ae-d43ec3c96fa7`` - -Now we have deployed JIMM and to verify that it is working properly you can try: - -``juju login jimm.canonical.domain.com`` - -and log in as user1. From this point on we will be using JIMM which will act as a Juju controller. - -Trying to list models will now show no models: - -``juju models`` - -Now we will also configure JIMM to serve the Juju Dashboard. The tarball needed for that is -included in the ``jimm.tar.xz`` that you have previously downloaded and is located in the dashboard -folder. First switch to the JIMM model: - -``juju switch infrastructure:jimm`` - -then we need to attach the dashboard tarball as a resource to JIMM: - -``juju attach-resource jimm dashboard=juju-dashboard-0.9.2.tar.bz2`` - -Before we can use JIMM though, we will need to add a controller to it. JIMM itself only forwards -requests to appropriate Juju controllers but can not directly control a model. - -Controller ----------- - -As stated above, we need to add a Juju controller to JIMM for each cloud (or cloud region) that we -want to be able to deploy to. For the purpose of this tutorial we will add a single controller that -will let us deploy to AWS. - -When bootstrapping a new Juju controller we will be defining some parameters that will tell the -controller which identity service to use to authenticate users (the Candid we had previously -deployed) and the DNS name for the server: - -``juju bootstrap --no-gui --bootstrap-constraints="root-disk=50G cores=8 mem=8G" --config identity-url=https://candid.canonical.domain.com --config allow-model-access=true --config public-dns-address=aws-1.canonical.domain.com:443 aws/eu-central-1 aws-1`` - -Please note that the constraints stated above are the ones used for production JAAS services and -should be suitable for most loads. Feel free to set constraints appropriate to your system. - -Next we put the controller into HA mode: - -``juju enable-ha`` - -which deploys two additional units of the controller increasing the resilience of the system. -Then you will need to switch to the controller model: - -``juju switch controller`` - -You can ensure you’re on the correct controller and model via: - -``juju whoami`` - -Download the controller `tarball `_ -and extract it: - -``tar xvf controller.tar.xz`` - -then move to the controller folder: - -``cd controller`` - -and deploy the controller bundle: - -``juju deploy --map-machines=existing ./bundle.yaml --overlay ./overlay-certbot.yaml`` - -Once the bundle is deployed you will again see that the HAProxy and certbot units are in error -state since we have not yet obtained a valid certificate for the deployed controller. - -Run the following to obtain the public IP of the HAProxy unit: - -``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` - - -Now you will need to go to the Route 53 dashboard again, navigate to the hosted zone for the canonical.domain.com subdomain and select Create record. We will add an A record for aws-1.canonical.domain.com with the value of the IP of the ``haproxy/0`` unit we obtained in the previous step. - -To obtain a valid certificate for the new controller we will use an action of the certbot charm. -Run: - -``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=aws-1.canonical.domain.com email= plugin=dns-route53`` - -It might take a while to get the certificate, but once complete: - -``juju status`` - -Once Juju status shows all Juju units as operational we can move to the next step, which is adding -this controller to JIMM. - -To achieve this, you will need to download and install the `JAAS snap `_. To install the snap run: - -``sudo snap install jaas_amd64.snap --dangerous`` - -Once you have installed the snap run: - -``/snap/jaas/current/bin/jimmctl controller-info --public-address=aws-1.:443 aws-1 aws-1.yaml`` - -to get the controller information in YAML format. Then to finally add the controller to JIMM -switch to the JIMM controller: - -``juju switch jimm.canonical.domain.com`` - -and run: - -``/snap/jaas/current/bin/jimmctl add-controller aws-1.yaml`` - - -To see the registered controller, head over to your domain in the browser: - -``jimm.`` - -And login using the credentials you provided the Candid earlier. - -Since we configured JIMM so that user1 is an admin user, you have to log in as user1 to be able to -add the controller. If needed, you can always run: - -.. code:: console - - juju logout - juju login jimm.canonical.domain.com - -to re-login. - -Workloads ---------- - -Now you have installed the JAAS system (Candid and JIMM) and added a controller to it, which means -we can now use it to deploy our workloads. - -Make sure we are using the JIMM controller, so just in case run: - -``juju switch jimm.canonical.domain.com`` - - -If we run: - -``juju list-credentials`` - -we will see the JIMM controller lacks your AWS credentials, we can upload these credentials from -your Juju client to the controller via: - -``juju update-credentials aws --controller jimm.`` - - -Now let’s make this tutorial fun and deploy Kubernetes using JAAS. First, we want to add a new -model for our Kubernetes deploy: - -``juju add-model k8s`` - - -Since we only have one controller in AWS, the new model will also be added in AWS. Juju makes -it really easy to deploy Kubernetes, run the following command: - -``juju deploy charmed-kubernetes`` - -and then we wait: - -``juju status --wait 4s --color`` - -Once the deploy finishes that is it - we have a functioning Kubernetes cluster. To start using it -you will want to install the ``kubectl`` snap: - -``sudo snap install kubectl --classic`` - -and fetch the config file from the newly deployed cluster: - - ``juju scp kubernetes-master/0:config ~/.kube/config`` :none:`wokeignore:rule=master,` - -You can verify everything is configured correctly and see the cluster by running: - -``kubectl cluster-info`` - -To add simple storage for Kubernetes using NFS run: - -.. code:: console - - juju deploy nfs --constraints root-disk=200G - juju add-relation nfs kubernetes-worker - -Dashboard ---------- - -Now you can open a browser and navigate to ``https://jimm.canonical.domain.com/dashboard`` -where you will find the Juju Dashboard. Again you will be asked to log in: log in as user1. -If you click on Models in the left pane, you will see the k8s model that we created for our -Kubernetes deploy. Click on k8s and you will see the entire Kubernetes cluster as deployed -by Juju. You can select individual applications to see details. - -Conclusion ----------- - -Following this tutorial you have deployed the JAAS system and used it to deploy a simple -Kubernetes cluster that you can use to deploy further workloads.