diff --git a/documentation/.gitignore b/documentation/.gitignore deleted file mode 100644 index c8f8ee69f..000000000 --- a/documentation/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -/*env*/ -.sphinx/venv -.sphinx/warnings.txt -.sphinx/.wordlist.dic -_build -.DS_Store -__pycache__ -.idea/ diff --git a/documentation/.sphinx/_static/custom.css b/documentation/.sphinx/_static/custom.css deleted file mode 100644 index b75217004..000000000 --- a/documentation/.sphinx/_static/custom.css +++ /dev/null @@ -1,189 +0,0 @@ -/** Fix the font weight (300 for normal, 400 for slightly bold) **/ - -div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head { - font-weight: 300 -} - -.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt { - font-weight: 400; -} - -/** Table styling **/ - -th.head { - text-transform: uppercase; - font-size: var(--font-size--small); -} - -table.docutils { - border: 0; - box-shadow: none; - width:100%; -} - -table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child { - border-right: none; - border-left: none; -} - -/* Centre text horizontally in table data cells */ -table.docutils td { - text-align: center; -} - -/** No rounded corners **/ - -.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight { - border-radius: 0; -} - -/** Admonition styling **/ - -.admonition { - border-top: 1px solid #d9d9d9; - border-right: 1px solid #d9d9d9; - border-bottom: 1px solid #d9d9d9; -} - -/** Color for the "copy link" symbol next to headings **/ - -a.headerlink { - color: var(--color-brand-primary); -} - -/** Line to the left of the current navigation entry **/ - -.sidebar-tree li.current-page { - border-left: 2px solid var(--color-brand-primary); -} - -/** Some tweaks for issue #16 **/ - -[role="tablist"] { - border-bottom: 1px solid var(--color-sidebar-item-background--hover); -} - -.sphinx-tabs-tab[aria-selected="true"] { - border: 0; - border-bottom: 2px solid var(--color-brand-primary); - background-color: var(--color-sidebar-item-background--current); - font-weight:300; -} - -.sphinx-tabs-tab{ - color: var(--color-brand-primary); - font-weight:300; -} - -.sphinx-tabs-panel { - border: 0; - border-bottom: 1px solid var(--color-sidebar-item-background--hover); - background: var(--color-background-primary); -} - -button.sphinx-tabs-tab:hover { - background-color: var(--color-sidebar-item-background--hover); -} - -/** Custom classes to fix scrolling in tables by decreasing the - font size or breaking certain columns. - Specify the classes in the Markdown file with, for example: - ```{rst-class} break-col-4 min-width-4-8 - ``` -**/ - -table.dec-font-size { - font-size: smaller; -} -table.break-col-1 td.text-left:first-child { - word-break: break-word; -} -table.break-col-4 td.text-left:nth-child(4) { - word-break: break-word; -} -table.min-width-1-15 td.text-left:first-child { - min-width: 15em; -} -table.min-width-4-8 td.text-left:nth-child(4) { - min-width: 8em; -} - -/** Underline for abbreviations **/ - -abbr[title] { - text-decoration: underline solid #cdcdcd; -} - -/** Use the same style for right-details as for left-details **/ -.bottom-of-page .right-details { - font-size: var(--font-size--small); - display: block; -} - -/** Version switcher */ -button.version_select { - color: var(--color-foreground-primary); - background-color: var(--color-toc-background); - padding: 5px 10px; - border: none; -} - -.version_select:hover, .version_select:focus { - background-color: var(--color-sidebar-item-background--hover); -} - -.version_dropdown { - position: relative; - display: inline-block; - text-align: right; - font-size: var(--sidebar-item-font-size); -} - -.available_versions { - display: none; - position: absolute; - right: 0px; - background-color: var(--color-toc-background); - box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); - z-index: 11; -} - -.available_versions a { - color: var(--color-foreground-primary); - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)} - -.show {display:block;} - -/** Fix for nested numbered list - the nested list is lettered **/ -ol.arabic ol.arabic { - list-style: lower-alpha; -} - -/** Make expandable sections look like links **/ -details summary { - color: var(--color-link); -} - -/** Fix the styling of the version box for readthedocs **/ - -#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version { - background: var(--color-sidebar-item-background--hover); -} - -.rst-versions .rst-other-versions dd a { - color: var(--color-link); -} - -#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions { - color: var(--color-sidebar-link-text); -} - -.rst-versions .rst-current-version { - color: var(--color-version-popup); - font-weight: bolder; -} diff --git a/documentation/.sphinx/_templates/footer.html b/documentation/.sphinx/_templates/footer.html deleted file mode 100644 index b7c93e08c..000000000 --- a/documentation/.sphinx/_templates/footer.html +++ /dev/null @@ -1,75 +0,0 @@ -{# ru-fu: copied from Furo, with modifications as stated below #} - -
- {% if next -%} - -
-
- {{ _("Next") }} -
-
{{ next.title }}
-
- - - {%- endif %} - {% if prev -%} - - -
-
- {{ _("Previous") }} -
- {% if prev.link == pathto(master_doc) %} -
{{ _("Home") }}
- {% else %} -
{{ prev.title }}
- {% endif %} -
- - {%- endif %} -
-
-
- {%- if show_copyright %} -
- {%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright|e -%} - Copyright © {{ copyright }} - {%- endtrans %} - {%- else %} - {% trans copyright=copyright|e -%} - Copyright © {{ copyright }} - {%- endtrans %} - {%- endif %} -
- {%- endif %} - - {# ru-fu: removed "Made with" #} - - {%- if last_updated -%} -
- {% trans last_updated=last_updated|e -%} - Last updated on {{ last_updated }} - {%- endtrans -%} -
- {%- endif %} -
-
- - {# ru-fu: replaced RTD icons with our links #} - - {%- if show_source and has_source and sourcename %} -
- Show source -
- {%- endif %} - {% if github_url and github_version and github_folder and github_filetype %} -
- Edit on GitHub -
- {% endif %} - -
-
- diff --git a/documentation/.sphinx/_templates/page.html b/documentation/.sphinx/_templates/page.html deleted file mode 100644 index ede3495c8..000000000 --- a/documentation/.sphinx/_templates/page.html +++ /dev/null @@ -1,44 +0,0 @@ -{% extends "furo/page.html" %} - -{% block footer %} - {% include "footer.html" %} -{% endblock footer %} - -{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} - {% set furo_hide_toc_orig = furo_hide_toc %} - {% set furo_hide_toc=false %} -{% endif %} - -{% block right_sidebar %} -
- {% if not furo_hide_toc_orig %} -
- - {{ _("Contents") }} - -
-
-
- {{ toc }} -
-
- {% endif %} - {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} -
- - Related links - -
-
-
- {% if meta.discourse and discourse_prefix %} - {{ discourse_links(meta.discourse) }} - {% endif %} - {% if meta.relatedlinks %} - {{ related_links(meta.relatedlinks) }} - {% endif %} -
-
- {% endif %} -
-{% endblock right_sidebar %} diff --git a/documentation/.sphinx/pinned-requirements.txt b/documentation/.sphinx/pinned-requirements.txt deleted file mode 100644 index 66fc4e970..000000000 --- a/documentation/.sphinx/pinned-requirements.txt +++ /dev/null @@ -1,57 +0,0 @@ -alabaster==0.7.13 -Babel==2.12.1 -beautifulsoup4==4.11.2 -bracex==2.3.post1 -certifi==2022.12.7 -charset-normalizer==3.1.0 -colorama==0.4.6 -contourpy==1.0.7 -cycler==0.11.0 -docutils==0.19 -fonttools==4.39.0 -furo==2022.12.7 -html5lib==1.1 -idna==3.4 -imagesize==1.4.1 -importlib-metadata==6.0.0 -importlib-resources==5.12.0 -Jinja2==3.1.2 -kiwisolver==1.4.4 -livereload==2.6.3 -lxd-sphinx-extensions==0.0.6 -lxml==4.9.2 -Markdown==3.4.1 -MarkupSafe==2.1.2 -matplotlib==3.7.1 -numpy==1.24.2 -packaging==23.0 -Pillow==9.4.0 -Pygments==2.14.0 -pyparsing==3.0.9 -pyspelling==2.8.2 -python-dateutil==2.8.2 -pytz==2022.7.1 -PyYAML==6.0 -requests==2.28.2 -six==1.16.0 -snowballstemmer==2.2.0 -soupsieve==2.4 -sphinx==6.1.3 -sphinx-autobuild==2021.3.14 -sphinx-basic-ng==1.0.0b1 -sphinx-copybutton==0.5.1 -sphinx-design==0.3.0 -sphinx-reredirects==0.1.1 -sphinx-tabs==3.4.1 -sphinxcontrib-applehelp==1.0.4 -sphinxcontrib-devhelp==1.0.2 -sphinxcontrib-htmlhelp==2.0.1 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.3 -sphinxcontrib-serializinghtml==1.1.5 -sphinxext-opengraph==0.8.1 -tornado==6.2 -urllib3==1.26.14 -wcmatch==8.4.1 -webencodings==0.5.1 -zipp==3.15.0 diff --git a/documentation/.sphinx/requirements.txt b/documentation/.sphinx/requirements.txt deleted file mode 100644 index e9a91bc34..000000000 --- a/documentation/.sphinx/requirements.txt +++ /dev/null @@ -1,10 +0,0 @@ -sphinx -sphinx-autobuild -sphinx-design -furo -sphinx-tabs -sphinx-reredirects -pyspelling -sphinxext-opengraph -lxd-sphinx-extensions -sphinx-copybutton diff --git a/documentation/.sphinx/spellingcheck.yaml b/documentation/.sphinx/spellingcheck.yaml deleted file mode 100644 index 8ee4a3c44..000000000 --- a/documentation/.sphinx/spellingcheck.yaml +++ /dev/null @@ -1,26 +0,0 @@ -matrix: -- name: rST files - aspell: - lang: en - d: en_GB - dictionary: - wordlists: - - .wordlist.txt - output: .sphinx/.wordlist.dic - sources: - - _build/**/*.html - pipeline: - - pyspelling.filters.html: - comments: false - attributes: - - title - - alt - ignores: - - code - - pre - - spellexception - - link - - title - - div.relatedlinks - - div.visually-hidden - - img diff --git a/documentation/.woke.yaml b/documentation/.woke.yaml deleted file mode 100644 index 9bb3d605a..000000000 --- a/documentation/.woke.yaml +++ /dev/null @@ -1,5 +0,0 @@ -ignore_files: - # Ignore sphinx and vscode files - - .sphinx/* - - .vscode/* - - ./.woke.yaml diff --git a/documentation/.wordlist.txt b/documentation/.wordlist.txt deleted file mode 100644 index 1b00b325e..000000000 --- a/documentation/.wordlist.txt +++ /dev/null @@ -1,9 +0,0 @@ -APIs -Permalink -ReadMe -roadmap -webhook -reST -reStructuredText -UI -https diff --git a/documentation/Makefile b/documentation/Makefile deleted file mode 100644 index 374f37653..000000000 --- a/documentation/Makefile +++ /dev/null @@ -1,63 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build -VENV = .sphinx/venv/bin/activate - - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -install: - @echo "Install woke" - go get github.com/get-woke/woke - go install github.com/get-woke/woke - @echo "... setting up virtualenv" - python3 -m venv .sphinx/venv - . $(VENV); pip install --upgrade -r .sphinx/requirements.txt - - @echo "\n" \ - "--------------------------------------------------------------- \n" \ - "* watch, build and serve the documentation: make run \n" \ - "* only build: make html \n" \ - "* only serve: make serve \n" \ - "* clean built doc files: make clean-doc \n" \ - "* clean full environment: make clean \n" \ - "* check spelling: make spelling \n" \ - "--------------------------------------------------------------- \n" -run: - . $(VENV); sphinx-autobuild --pre-build "woke **/*.rst" -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" - -html: - . $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt - -epub: - . $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt - -serve: - cd "$(BUILDDIR)"; python3 -m http.server 8000 - -clean: clean-doc - rm -rf .sphinx/venv - -clean-doc: - git clean -fx "$(BUILDDIR)" - -spelling: html - . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml - -linkcheck: - . $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/documentation/README.md b/documentation/README.md index b5285ed34..9dda82a6a 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,22 +1,5 @@ JAAS Documenation ========================== -This directory holds the JAAS documentation: - -- tutorials -- how-tos -- reference -- explanations - -How to use ----------- - -To compile the documentation locally run: - -`` make install`` - -followed by: - -``make run`` - -and then visit http://127.0.0.1:8000 \ No newline at end of file +Public JAAS documentation can be found at https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/ +Source code for the docs can be found at https://github.com/canonical/jaas-documentation \ No newline at end of file diff --git a/documentation/conf.py b/documentation/conf.py deleted file mode 100644 index 3af186a9c..000000000 --- a/documentation/conf.py +++ /dev/null @@ -1,133 +0,0 @@ -import sys - -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "JAAS Documentation" -author = "Canonical Group Ltd" -copyright = "%s, %s" % ("2023", author) -release = "1.0" - -# Open Graph configuration - defines what is displayed in the website preview -ogp_site_url = "https://canonical-jimm.readthedocs-hosted.com/" -ogp_site_name = project -ogp_image = ( - "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" -) - -html_context = { - # Change to the discourse instance you want to be able to link to - "discourse_prefix": "https://discourse.ubuntu.com/t/", - # Change to the GitHub info for your project - "github_url": "https://github.com/canonicaljimm", - "github_version": "main", - "github_folder": "/", - "github_filetype": "rst", -} - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx_design", - "sphinx_tabs.tabs", - "sphinx_reredirects", - "youtube-links", - "related-links", - "custom-rst-roles", - "sphinx_copybutton", - "sphinxext.opengraph", -] - -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".sphinx"] - -rst_epilog = """ -.. include:: /reuse/links.txt -""" - -# Links to ignore when checking links -linkcheck_ignore = ["http://127.0.0.1:8000"] - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# Find the current builder -builder = "dirhtml" -if "-b" in sys.argv: - builder = sys.argv[sys.argv.index("-b") + 1] - -# Setting templates_path for epub makes the build fail -if builder == "dirhtml" or builder == "html": - templates_path = [".sphinx/_templates"] - -html_theme = "furo" -html_last_updated_fmt = "" -html_permalinks_icon = "¶" -html_theme_options = { - "light_css_variables": { - "color-sidebar-background-border": "none", - "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif", - "font-stack--monospace": "Ubuntu Mono, Consolas, Monaco, Courier, monospace", - "color-foreground-primary": "#111", - "color-foreground-secondary": "var(--color-foreground-primary)", - "color-foreground-muted": "#333", - "color-background-secondary": "#FFF", - "color-background-hover": "#f2f2f2", - "color-brand-primary": "#111", - "color-brand-content": "#06C", - "color-api-background": "#cdcdcd", - "color-inline-code-background": "rgba(0,0,0,.03)", - "color-sidebar-link-text": "#111", - "color-sidebar-item-background--current": "#ebebeb", - "color-sidebar-item-background--hover": "#f2f2f2", - "toc-font-size": "var(--font-size--small)", - "color-admonition-title-background--note": "var(--color-background-primary)", - "color-admonition-title-background--tip": "var(--color-background-primary)", - "color-admonition-title-background--important": "var(--color-background-primary)", - "color-admonition-title-background--caution": "var(--color-background-primary)", - "color-admonition-title--note": "#24598F", - "color-admonition-title--tip": "#24598F", - "color-admonition-title--important": "#C7162B", - "color-admonition-title--caution": "#F99B11", - "color-highlighted-background": "#EbEbEb", - "color-link-underline": "var(--color-background-primary)", - "color-link-underline--hover": "var(--color-background-primary)", - "color-version-popup": "#772953", - }, - "dark_css_variables": { - "color-foreground-secondary": "var(--color-foreground-primary)", - "color-foreground-muted": "#CDCDCD", - "color-background-secondary": "var(--color-background-primary)", - "color-background-hover": "#666", - "color-brand-primary": "#fff", - "color-brand-content": "#06C", - "color-sidebar-link-text": "#f7f7f7", - "color-sidebar-item-background--current": "#666", - "color-sidebar-item-background--hover": "#333", - "color-admonition-background": "transparent", - "color-admonition-title-background--note": "var(--color-background-primary)", - "color-admonition-title-background--tip": "var(--color-background-primary)", - "color-admonition-title-background--important": "var(--color-background-primary)", - "color-admonition-title-background--caution": "var(--color-background-primary)", - "color-admonition-title--note": "#24598F", - "color-admonition-title--tip": "#24598F", - "color-admonition-title--important": "#C7162B", - "color-admonition-title--caution": "#F99B11", - "color-highlighted-background": "#666", - "color-link-underline": "var(--color-background-primary)", - "color-link-underline--hover": "var(--color-background-primary)", - "color-version-popup": "#F29879", - }, -} - -html_static_path = [".sphinx/_static"] -html_css_files = ["custom.css"] - -# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) -# For example: "explanation/old-name.html": "../how-to/prettify.html", -redirects = {} diff --git a/documentation/doc-cheat-sheet.rst b/documentation/doc-cheat-sheet.rst deleted file mode 100644 index 8c2c70ca3..000000000 --- a/documentation/doc-cheat-sheet.rst +++ /dev/null @@ -1,219 +0,0 @@ -:orphan: - -.. _cheat-sheet: - -reStructuredText cheat sheet -============================ - -This file contains the syntax for commonly used reST markup. -See the `reStructuredText style guide `_ for detailed information and conventions. - -Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. - -H2 heading ----------- - -H3 heading -~~~~~~~~~~ - -H4 heading -^^^^^^^^^^ - -H5 heading -.......... - -Inline formatting ------------------ - -- :guilabel:`UI element` -- ``code`` -- :file:`file path` -- :command:`command` -- *Italic* -- **Bold** - -Code blocks ------------ - -Start a code block:: - - code: - - example: true - -.. code:: - - # Demonstrate a code block - code: - - example: true - -.. code:: yaml - - # Demonstrate a code block - code: - - example: true - -.. _a_section_target: - -Links ------ - -- `Canonical website `_ -- `Canonical website`_ (defined in ``reuse/links.txt``) -- `Link defined at the bottom of the page`_ -- https:\ //canonical.com/ -- :ref:`a_section_target` -- :ref:`Link text ` -- :doc:`reference/index` -- :doc:`Link text ` - - -Navigation ----------- - -Use the following syntax:: - - .. toctree:: - :hidden: - - sub-page1 - sub-page2 - - -Lists ------ - -1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 -#. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - -Term 1: - Definition -Term 2: - Definition - -Tables ------- - -+----------------------+------------+ -| Header 1 | Header 2 | -+======================+============+ -| Cell 1 | Cell 2 | -| | | -| Second paragraph | | -+----------------------+------------+ -| Cell 3 | Cell 4 | -+----------------------+------------+ - -.. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph - - Cell 2 - * - Cell 3 - - Cell 4 - -Notes ------ - -.. note:: - A note. - -.. tip:: - A tip. - -.. important:: - Important information - -.. caution:: - This might damage your hardware! - -Images ------- - -.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - -.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - -Reuse ------ - -.. |reuse_key| replace:: This is **included** text. - -|reuse_key| - -.. include:: reference/index.rst - :start-after: adipiscing elit. - :end-before: Sed tincidunt sagittis orci - -Tabs ----- - -.. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - - -Glossary --------- - -.. glossary:: - - example term - Definition of the example term. - -:term:`example term` - -More useful markup ------------------- - -- .. versionadded:: X.Y -- | Line 1 - | Line 2 - | Line 3 -- .. This is a comment -- :abbr:`API (Application Programming Interface)` - ----- - -Custom extensions ------------------ - -Related links at the top of the page:: - - :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) - :discourse: 12345 - -.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - -:spellexception:`PurposelyWrong` - - -.. LINKS -.. _Link defined at the bottom of the page: https://canonical.com/ diff --git a/documentation/explanation/index.rst b/documentation/explanation/index.rst deleted file mode 100644 index 08b2fc240..000000000 --- a/documentation/explanation/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Explanation -=========== - - -.. toctree:: - :maxdepth: 1 - - JAAS tags - - -- Candid - authentication server - -- JIMM - Juju Intelligent Model Manager - -- `Juju `_ - diff --git a/documentation/explanation/jaas_tags.rst b/documentation/explanation/jaas_tags.rst deleted file mode 100644 index 161c25692..000000000 --- a/documentation/explanation/jaas_tags.rst +++ /dev/null @@ -1,78 +0,0 @@ -JAAS tags -========= - -Introduction ------------- - -When dealing with Relation Based Access Control (**ReBAC**) in JAAS we -use **JAAS tags** when referring to resources. - -Each **JAAS tag** uniquely identifies a resource. - -Users ------ - -A user tag has the following format: - -.. code:: console - - user- - -where *username* uniquely identifies a user including the domain specified -by Candid. - -Group ------ - -A group tag has the following format: - -.. code:: console - - group- - group- - -where *group id* represents the internal ID of the group. Most commonly we -refer to groups by their group name. - -Controller ----------- - -A controller tag has the following format: - -.. code:: console - - controller- - -Cloud ----------- - -A cloud tag has the following format: - -.. code:: console - - cloud- - -Model ------ - -A model tag has the following format: - -.. code:: console - - model-/ - -where *controller name* specifies name of the controller on which the model -is running and *model name* specifies the name of the model. - -Application offer ------------------ - -An application offer tag has the following format: - -.. code:: console - - applicationoffer-/. - -where *controller name* specifies name of the controller on which the model -is running, *model name* specifies name of the model in which the application -offer was created and *offer name* specifies the name of the application offer. \ No newline at end of file diff --git a/documentation/how-to/add_controller.rst b/documentation/how-to/add_controller.rst deleted file mode 100644 index a5aa0fd2b..000000000 --- a/documentation/how-to/add_controller.rst +++ /dev/null @@ -1,123 +0,0 @@ -JAAS: Add controller to JIMM -============================ - -Introduction ------------- - -JIMM gives a centralized view of all models in the system. However the work of managing -the models is delegated to a set of standard juju controllers deployed in various clouds -and regions. - -These juju controllers must be deployed with some specific options to ensure they work -correctly in the JAAS system. This document discusses how to bootstrap a juju controller -such that it will work correctly in a JAAS system. - -This document is for juju 2.x controllers, juju 3 will introduce the juju-controller -application in the controller model by default which will necessitate a (hopefully -small) reworking of this procedure. - -In this tutorial we will be bootstrapping a new juju controller in AWS and adding it to -JIMM. - -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`. In this tutorial we will assume that you have registered the canonical.example.com subdomain - please replace this with the appropriate subdomain that you have registered with Route 53. -- Admin access to a JIMM controller (see this tutorial). For this tutorial we will assume this JIMM is located at jimm.canonical.example.com - -Deploy controller ------------------ - -1. First we will prepare some parameters for the new controller and export environment variables that we will use in this tutorial. - - The **controller name** is the name given to the controller both on the local system and within JIMM. For visibility this often includes the name of the JAAS system, the cloud, the cloud-region and some kind of unique identifier, for example jaas-aws-us-east-1-001. - - The **cloud** is the cloud in which the controller is being bootstrapped. - - The **cloud region** is the region in which the controller is being bootstrapped. - - The **DNS name** is the full DNS name that will be given to the controller, often it is wise to make the hostname the same as the controller name within a particular domain. - - The **Candid URL** is the URL of the candid server that is providing the centralized identity service for the JAAS system. - - The **JIMM URL** is the URL of the JIMM system providing the JAAS service. - - +----------------------+----------------------+ - | Parameter | Environment variable | - +======================+======================+ - | Controller nam | $NAME | - +----------------------+----------------------+ - | Cloud | $CLOUD | - +----------------------+----------------------+ - | Cloud Region | $REGION | - +----------------------+----------------------+ - | DNS name | $DNS | - +----------------------+----------------------+ - | Candid URL | $CANDID | - +----------------------+----------------------+ - | JIMM URL | $JIMM | - +----------------------+----------------------+ - - -2. Now we are ready to bootstrap a controller. Please note the constraints here are the ones used for production JAAS services and should be suitable for most loads. If it is anticipated that the JAAS system will have a different model profile then we encourage you to determine the appropriate constraints for your system: - - ``juju bootstrap --no-gui --bootstrap-constraints="root-disk=50G cores=8 mem=8G" --config identity-url=$CANDID --config allow-model-access=true --config public-dns-address=$DNS:443 $CLOUD/$REGION $NAME`` - -3. Next the controller should be put into HA mode: - - ``juju enable-ha`` - -4. The we switch to the controller model: - - ``juju switch controller`` - -5. Download the controller bundle from: - - https://drive.google.com/file/d/17GHATHXGg2GuIeIWGr0FvkguMRdv5vnH/view?usp=sharing - -6. Uncompress the file: - - ``tar xvf controller.tar.xz`` - -7. Move to the controller folder: - - ``cd controller`` - -8. Deploy the bundle: - - ``juju deploy ./bundle.yaml --overlay ./overlay-certbot.yaml --map-machines=existing`` - -9. 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"]'`` - -10. Go to the `Route 53 dashboard `_. - -11. Add an A record for the deployed controller and the DNS name specified in step 1 with the IP obtained in step 9. - -12. 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`` - -13. Install the jaas snap that you download here: - - https://drive.google.com/file/d/1LiOvVpVQ13V3x3l2PhgS2fTHDUtCEe7p/view?usp=sharing - -14. To add the bootstrapped controller to JIMM we need to create a controller-information document. To do this, run the following command: - - ``/snap/jaas/current/bin/jimmctl controller-info –public-address=$DNS:443 $NAME $NAME.yaml`` - -15. Now we can switch to JIMM: - - ``juju switch $JIMM`` - -16. And add the controller to JIMM with the command: - - ``/snap/jaas/current/bin/jimmctl add-controller $NAME.yaml`` - -Following these steps you added an AWS controller to your JIMM. You should now be able to add models in AWS: juju add-model test aws diff --git a/documentation/how-to/candid_adfs_integration.rst b/documentation/how-to/candid_adfs_integration.rst deleted file mode 100644 index aa4df6559..000000000 --- a/documentation/how-to/candid_adfs_integration.rst +++ /dev/null @@ -1,186 +0,0 @@ -JAAS: Candid ADFS Integration -============================= - -Introduction ------------- - -This how-to will teach you how to set up an AFDS identity provider for Candid. - -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`. - -Candid ------- - -The first 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 2s –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. subdomain and select Create record. We will add an A record for candid.canonical. 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. 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.`` -which will tell Candid which DNS it is running on. - -Azure ------ - -Usually you will already have a tenant set up in Azure Active Directory, but for the sake of -completeness, this howto will guide you through the process of setting one up. -Open your web browser and navigate to the `Azure Portal `_. -Search for `Azure Active Directory` and click on Manage tenants and then click on Create. You -will be presented with the following form: - -.. image:: images/adfs_image5.png - -Select `Azure Active Directory` and click on `Next: Configuration`, which will show you the -following form: - -.. image:: images/adfs_image12.png - -Enter the desired `Organization name`, `Initial domain name` (record this value as we will need -it to configure Candid) and select an appropriate Country/Region, then click Review + create, -which will show you the review form: - -.. image:: images/adfs_image1.png - -If you’re satisfied with the entered data, click `Create`. You will be presented with a form -displaying information about the created tenant. Record the `Tenant ID`, as you will need it -later when configuring Candid. - -.. image:: images/adfs_image8.png - -To create a new user click on `Users` and then `New user` which will present you with the -following form where you can enter information about the new user. - -.. image:: images/adfs_image11.png - -Next we want to create a few groups, so select `Groups` from the left hand side menu and -create groups by clicking `New group` and entering relevant information. Created groups will -be displayed as shown in the following form: - -.. image:: images/adfs_image9.png - -To make the new user member of any of these groups, click on the group name, then click on -`Members` and then `Add members`. Start typing in the username and the portal should list -users matching the entered username. Select the newly created user and click `Select` as shown -in the following form: - -.. image:: images/adfs_image10.png - -Once you have finished creating groups and users it is time to register an application. Return -to the tenant overview form and click `App registrations`. In the following form enter the -application name, select `Accounts in this organizational directory only (Single tenant)` and -for the `Redirect URI` select `Web` and enter `https:///login/adfs/callback` as -the redirect URI. - -.. image:: images/adfs_image3.png - -When you click `Register` you will be shown a form displaying data about the registered -application. Record the `Application (client) ID` as you will need it later when configuring -Candid. - -.. image:: images/adfs_image13.png - -To give Candid access, we need to create a secret it will use to authenticate. Click on -`Certificates & secrets` and then `New client secret`. - -.. image:: images/adfs_image4.png - -Record the displayed secret Value. - -To give Candid permission to read user groups navigate to `API Permissions` and add permissions -under `Microsoft Graph: Group.Read.All`. - -.. image:: images/adfs_image14.png - -Then go to `Token configuration` to add additional claims. Click on `Add groups claim` so that -the Azure callback will include additional groups(s) claim. - -Configuring Candid ------------------- - -Next we need to add Azure as an identity provider to Candid, with the application (client) id -and the client secret we created in the previous step. Run: - -.. code-block:: bash - - juju config candid identity-providers='- type: adfs - domain: .onmicrosoft.com - url: https://login.microsoftonline.com//v2.0 - client-id: - client-secret: - match-email-addr: "@.onmicrosoft.com$"' - -For the domain name enter the `Initial domain name` you entered when creating the new tenant. And -the tenant id is the ID of the created tenant. For the client-id enter the `Application (client) ID` -you recorded when registering a new application. The client-secret is the Value you recorded when -creating a new client secret for the registered application. - -Then we can test Candid by opening your browser and going to -https://candid.canonical./login, which will present you with a page allowing you to -login with ADFS. - -.. image:: images/adfs_image7.png - - -After you select ADFS identity provider you will have to log in with Azure and then Candid will -present you with a page allowing you to register a new user by specifying the username. - -.. image:: images/adfs_image15.png - -After you click Register, Candid will show a page notifying you that you have successfully logged -in. - -.. image:: images/adfs_image6.png - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and configured it to let you log in with your -ADFS credentials. - -To teardown your model and controller use the following command. -This will free all resources created on the cloud provider used. - -``juju destroy-controller --destroy-all-models --destroy-storage mycontroller`` - - - - diff --git a/documentation/how-to/candid_azure_integration.rst b/documentation/how-to/candid_azure_integration.rst deleted file mode 100644 index 0e1d6230f..000000000 --- a/documentation/how-to/candid_azure_integration.rst +++ /dev/null @@ -1,104 +0,0 @@ -JAAS: Candid Azure Integration -============================== - -Introduction ------------- - -This how-to will teach you how to set up an Azure identity provider for Candid. - -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`. - -Candid ------- - -The first 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 2s –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. subdomain and select Create record. We will add an A record for candid.canonical. 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. 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.`` -which will tell Candid which DNS it is running on. - -Azure ------ - -With Candid deploy, we need credentials that will let Candid user Azure. -To do that open your browser and go to the Azure portal Find App Registration as we need to register a new application. The Azure portal will show you the following screen: - -.. image:: images/azure_image3.png - -where you will enter the application name and choose “Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)” when specifying who can access this API. -for the Redirect URI choose “Web” and enter “https://candid.canonical./login/azure/callback” as the callback URI. -After clicking “Register” you will be taken to the App Registration page, where you will find the “Application (client) ID”, which you need to copy. Then select “Certificates & secrets” in the management menu, because we will need to create a new secret. - -.. image:: images/azure_image2.png - -When you select “New client secret” it will prompt you to enter a name for it and then it will show you a page displaying the created secret value and ID. Copy the secret value as we will need it when configuring Candid. - -.. image:: images/azure_image5.png - -Configuring Candid ------------------- - -Next we need to add Azure as an identity provider to Candid, with the application (client) id and the client secret we created in the previous step. Run: - -.. code:: console - - juju config candid identity-providers='- type: azure - client-id: - client-secret: - -Then we can test Candid by opening your browser and going to “https://candid.canonical./login”, which will present you with a page allowing you to login with Azure. - -.. image:: images/azure_image1.png - -After you select Azure identity provider you will have to log in with Azure and then Candid will present you with a page allowing you to register a new user by specifying the username. - -.. image:: images/azure_image4.png - -After you click Register, Candid will show a page notifying you that you have successfully logged in. - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and configured it to let you log in with your Azure credentials. - diff --git a/documentation/how-to/candid_ldap_integration.rst b/documentation/how-to/candid_ldap_integration.rst deleted file mode 100644 index 8ad929b63..000000000 --- a/documentation/how-to/candid_ldap_integration.rst +++ /dev/null @@ -1,276 +0,0 @@ -JAAS: Candid LDAP Integration -============================= - -Introduction ------------- - -This how-to will teach you how to set up an LDAP identity provider for Candid. - -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`. - -Candid ------- - -The first 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 2s –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. subdomain and select Create record. We will add an A record for candid.canonical. 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. 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.`` -which will tell Candid which DNS it is running on. - -LDAP ----- - -In real-world scenarios you will already have a LDAP deploy, which you will use with candid. But for the sake of completeness this section will show you how to manually deploy and configure OpenLDAP (deploy using charms will be described in a separate document as we currently do not have an OpenLDAP machine charm). -First we create a model for the LDAP deploy: - -``juju add-model ldap`` - -Then we deploy a basic Ubuntu unit and a certbot charm: - -.. code:: - - juju deploy ubuntu ldap - juju deploy cs:~yellow/certbot - -and wait for the units to deploy. - -Install OpenLDAP -~~~~~~~~~~~~~~~~ - -As stated above, we will manually deploy OpenLDAP as we currently do not have a machine charm for it. -SSH into the unit: - -``juju ssh ldap/0`` - -And install OpenLDAP by running: - -``sudo apt install slapd ldap-utils`` - -Having installed OpenLDAP run: - -``sudo dpkg-reconfigure slapd`` - -Which will take you through the process of reconfiguring OpenLDAP. -First, you will be presented with the following screen. - -.. image:: images/ldap_image2.png - -Answer “No”. -When asked to enter then DNS domain name - -.. image:: images/ldap_image1.png - -enter “ldap.canonical.” replacing the “” part with the name of the domain you own. - -In the next screen enter “canonical.” as the name of the organization again, replacing “domain.com” with the domain you own. - -.. image:: images/ldap_image3.png - -Next you will have to enter an administrator password. - -.. image:: images/ldap_image8.png - -And re-enter the chosen administrator password. - -.. image:: images/ldap_image4.png - -When asked if you want the database removed when slapd is purged, it is safe to answer “No.” as this is there is no content in the database yet. - -.. image:: images/ldap_image7.png - -Having configured OpenLDAP you can exit from the unit. - - -Configure TLS -~~~~~~~~~~~~~ - -To obtain a valid certificate for OpenLDAP we will use certbot. -First we need to tell certbot where to place obtained certificate, key and trust chain: - -.. code:: console - - juju config certbot chain-path=/etc/ldap/ldap-chain.pem - juju config certbot key-path=/etc/ldap/ldap-key.pem - juju config certbot cert-path=/etc/ldap/ldap-cert.pem - -Now we can add a relation between certbot and ldap applications: - -``juju add-relation certbot ldap`` - -Next we’ll need to create a DNS **A** record for the LDAP in Route53. -Run: - -``juju status --format json | jq '.applications.ldap.units["ldap/0"]["public-address"]'`` - -to obtain the public IP of the LDAP unit and use that IP to create an **A** record for the DNS ldap.canonical.. -Then we can run the get-certificate action on the certbot unit to obtain certificates; - -``juju run-action –wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains=ldap.canonical. email= plugin=dns-route53`` - -This will result in creation of .pem files specified by the certbot configuration. -Now we can ssh back into the ldap unit: - -.. code:: console - - juju ssh ldap/0 - cd /etc/ldap - -Next we need to configure OpenLDAP to use created certificates. -We do that by creating a file certinfo.ldif with the following content - -.. code:: yaml - - dn: cn=config - replace: olcTLSCACertificateFile - olcTLSCACertificateFile: /etc/ldap/ldap-chain.pem - - - replace: olcTLSCertificateFile - olcTLSCertificateFile: /etc/ldap/ldap-cert.pem - - - replace: olcTLSCertificateKeyFile - olcTLSCertificateKeyFile: /etc/ldap/ldap-key.pem - -And then apply this configuration to OpenLDAP: - -``sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f certinfo.ldif`` - -Allowing access to LDAP -~~~~~~~~~~~~~~~~~~~~~~~ - -As we have manually deployed OpenLDAP, we need to allow access to its ports. To do that go to the EC2 management console, to the list of running instances. Identify the OpenLDAP unit by its IP and edit its security groups. Add a rule that allows access to the LDAP port (389) from anywhere on the web. - -Initial LDAP content -~~~~~~~~~~~~~~~~~~~~ - -Next we create a file content.ldif with the following content: - -.. code:: yaml - - dn: ou=People,dc=canonical,dc=,dc= - objectClass: organizationalUnit - ou: People - - dn: ou=Groups,dc=canonical,dc=,dc= - objectClass: organizationalUnit - ou: Groups - -And add that to OpenLDAP: - -``ldapadd -x -D cn=admin,dc=canonical,dc=,dc= -W -f ./content.ldif`` - -Adding users -~~~~~~~~~~~~ - -To add an LDAP user, we create a file names .ldif with the following content: - -.. code:: yaml - - dn: uid=,ou=People,dc=canonical,dc=,dc= - objectClass: inetOrgPerson - objectClass: posixAccount - objectClass: shadowAccount - uid: - sn: - givenName: - cn: - displayName: - uidNumber: - gidNumber: - userPassword: {CRYPT}x - gecos: - loginShell: /bin/bash - homeDirectory: /home/ - -And use ldapadd to add the user: - -``ldapadd -x -D cn=admin,dc=canonical,dc=,dc= -W -f ./.ldif`` - -Next we need to set a password for the created user, which we do by running: - -``ldappasswd -x -D cn=admin,dc=canonical,dc=,dc= -W -S uid=,ou=People,dc=canonical,dc=,dc=`` - - -LDAP Identity Provider for Candid ---------------------------------- - -Once we have Candid deployed and LDAP configured all we need to do is let Candid know how to use OpenLDAP as an identity provider. We do this by setting its identity-providers config option: - -.. code:: console - - juju config candid identity-providers='- type: ldap - name: - description: - domain: ldap.canonical. - url: ldap://ldap.canonical./dc=canonical,dc=,dc= - dn: cn=admin,dc=canonical,dc=,dc= - password: - user-query-filter: (objectClass=inetOrgPerson) - user-query-attrs: - id: uid - email: mail - display-name: displayName - group-query-filter: (&(objectClass=groupOfNames)(member={{.User}})) - hidden: false - ca-cert: | - - - -Testing Candid with LDAP ------------------------- - -To test Candid you can open your browser and go to https://candid.canonical./login which will present you with the following page: - -.. image:: images/ldap_image6.png - -as we only have one identity provider configured - LDAP. Clicking on ldap will present you with the following page: - -.. image:: images/ldap_image5.png - -where you are asked to provide username and password for one of the users you added to LDAP. If you enter the correct credentials, Candid will show you a page notifying you that you have successfully logged in. - -Conclusion ----------- - -In this how-to we have successfully deployed Candid and OpenLDAP and configured Candid to let you log in with your OpenLDAP credentials. - diff --git a/documentation/how-to/deploy_candid.rst b/documentation/how-to/deploy_candid.rst deleted file mode 100644 index 09f58854e..000000000 --- a/documentation/how-to/deploy_candid.rst +++ /dev/null @@ -1,84 +0,0 @@ -JAAS: Deploy Candid -=================== - -Introduction -In this tutorial we will be deploying Candid. Candid provides a macaroon-based authentication service that is able to utilize many standard identity providers: - -- UbuntuSSO -- LDAP -- Google OpenID Connect -- ADFS OpenID Connect -- Azure OpenID Connect -- Keystore (userpass or token) -- Static identity provider (only used for testing) - -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`. In this tutorial we will assume that you have registered the canonical.example.com subdomain - please replace this with the appropriate subdomain that you have registered with Route 53. - -Deploy Candid -------------- - -1. Bootstrap a controller: - ``juju bootstrap aws`` -2. Download the candid bundle from: - https://drive.google.com/file/d/1ZyZeI0jNacbXK-AgxzUT0IUEp9tQ85QH/view?usp=sharing - -3. Uncompress the file: - ``tar xvf candid_v1.11.0.tar.xz `` - -4. Move to the candid folder: - ``cd candid`` - -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 candid (e.g. candid.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 candid know its DNS name (replace candid.canonical.example.com with the DNS name you set up in step 8): - ``juju config candid location=https://candid.canonical.example.com`` - -11. 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:: - - juju config candid identity-providers='- type: static - name: static - description: Default identity provider - users: - user1: - name: User One - email: user1 - password: s3cre7Pa55w0rd1 - groups: - - group1 - - group3 - user2: - name: User Two - email: user2 - password: s3cre7Pa55w0rd2 - groups: - - group2 - - group3' - -Following these steps you have deployed Candid that uses a static identity provider -with two hardcoded users. **Please note that the static identity provider should not -be used in production**. - -To verify that Candid is working correctly, open your browser and go to -https:///login and try to log in as “user1” or “user2” using one of the -hardcoded passwords. \ No newline at end of file diff --git a/documentation/how-to/deploy_candid_k8s.rst b/documentation/how-to/deploy_candid_k8s.rst deleted file mode 100644 index 257a50909..000000000 --- a/documentation/how-to/deploy_candid_k8s.rst +++ /dev/null @@ -1,289 +0,0 @@ -JAAS: Deploy Candid on K8S -========================== - -Introduction ------------- - -In this howto we will be deploying Candid on Kubernetes. Candid provides a macaroon-based authentication service that is able to utilize many standard identity providers: - -- UbuntuSSO -- LDAP -- Google OpenID Connect -- ADFS OpenID Connect -- Azure OpenID Connect -- Keystore (userpass or token) -- Static identity provider (only used for testing) - -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:: console - - 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 Candid -------------- - -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 Candid: - -``juju add-model candid`` - -Now we can deploy the Candid into the newly created model: - -``juju deploy candid-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:: console - - juju deploy nginx-ingress-integrator ingress - juju trust ingress --scope=cluster - juju relate ingress candid-k8s - -Once deployed go to the management console of your domain and create an A record for the deployed Candid (e.g. candidcanonical.example.com) with the IP of k8s worker nodes. - -Configure Candid ----------------- - -Once deployed we need to configure Candid. Run the following commands: - -.. code:: console - - juju config candid-k8s location=https://candid.canonical.stimec.net - juju config candid-k8s admin-agent-public-key='test-public-key' - - juju config candid-k8s identity-providers='- type: static - name: static - domain: stimec - description: Default identity provider - users: - admin: - name: User One - email: admin - password: password1 - groups: - - group1 - user1: - name: User Two - email: user1 - password: password1 - groups: - - group2 - my-user: - name: User Three - email: my-user - password: password1 - groups: - - group2' - juju config candid-k8s postgresql-dsn= - - -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 Candid’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 test Candid by opening your browser and navigating to https://candid./login - -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 customize all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” adn “Port” strings, which you will need to connect to the database. Use the following command to configure Candid: - -``juju config candid-k8s dns=’postgres://:@:/`` - -Don’t have certificates -~~~~~~~~~~~~~~~~~~~~~~~ - -In case the cluster operator did not set up a Kubernetes secret for you containing certificate and key for Candid’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:: console - - 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 fille 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 candid -f stg-issuer.yaml`` - -which will create a certificate issuer in candid’s namespace. - -The create stg-certs.yaml file with the following content: - -.. code:: yaml - - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: candid-stg-cert #name of this object - namespace: candid #same namespace as - spec: - dnsNames: - - candid.canonical.stimec.net - secretName: letsencrypt-stg-certs - issuerRef: - name: letsencrypt-staging - kind: Issuer - -and run: - -``kubectl apply -n candid -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 candid candid-stg-cert`` - -and: - -``kubectl describe secret letsencrypt-stg-certs -n candid`` - -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 candid -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: candid-cert #name of this object - namespace: candid - spec: - dnsNames: - - candid.canonical.stimec.net - secretName: letsencrypt-certs - issuerRef: - name: letsencrypt-prod - kind: Issuer - -and run: - -``kubectl apply -n candid -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 candid`` - -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 candid candid-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/documentation/how-to/deploy_jimm.rst b/documentation/how-to/deploy_jimm.rst deleted file mode 100644 index 8b6541e00..000000000 --- a/documentation/how-to/deploy_jimm.rst +++ /dev/null @@ -1,42 +0,0 @@ -JAAS: Deploy JIMM -================= - -Introduction ------------- - -In this howto 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: https://drive.google.com/file/d/19IFY7m-GW1AdKUzKdKbUO_bSE6zv8tNH/view?usp=sharing -3. Uncompress 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/documentation/how-to/deploy_jimm_k8s.rst b/documentation/how-to/deploy_jimm_k8s.rst deleted file mode 100644 index 34b1fb144..000000000 --- a/documentation/how-to/deploy_jimm_k8s.rst +++ /dev/null @@ -1,256 +0,0 @@ -JAAS: Deploy JIMM on K8S -======================== - -Introduction ------------- - -In this howto 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 customize all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” adn “Port” strings, which you will need to connect to the database. Use the following command to configure JIMM: - -``juju config jimm-k8s dns=’postgres://:@:/`` - -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 fille 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/documentation/how-to/images/adfs_image1.png b/documentation/how-to/images/adfs_image1.png deleted file mode 100644 index 0e82309c5..000000000 Binary files a/documentation/how-to/images/adfs_image1.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image10.png b/documentation/how-to/images/adfs_image10.png deleted file mode 100644 index 813691325..000000000 Binary files a/documentation/how-to/images/adfs_image10.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image11.png b/documentation/how-to/images/adfs_image11.png deleted file mode 100644 index 5fdb0e8d5..000000000 Binary files a/documentation/how-to/images/adfs_image11.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image12.png b/documentation/how-to/images/adfs_image12.png deleted file mode 100644 index e90502997..000000000 Binary files a/documentation/how-to/images/adfs_image12.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image13.png b/documentation/how-to/images/adfs_image13.png deleted file mode 100644 index 8ef747f14..000000000 Binary files a/documentation/how-to/images/adfs_image13.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image14.png b/documentation/how-to/images/adfs_image14.png deleted file mode 100644 index 3f8066626..000000000 Binary files a/documentation/how-to/images/adfs_image14.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image15.png b/documentation/how-to/images/adfs_image15.png deleted file mode 100644 index 2a60f8c94..000000000 Binary files a/documentation/how-to/images/adfs_image15.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image2.png b/documentation/how-to/images/adfs_image2.png deleted file mode 100644 index e6f16a2eb..000000000 Binary files a/documentation/how-to/images/adfs_image2.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image3.png b/documentation/how-to/images/adfs_image3.png deleted file mode 100644 index 87a8da03c..000000000 Binary files a/documentation/how-to/images/adfs_image3.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image4.png b/documentation/how-to/images/adfs_image4.png deleted file mode 100644 index 3c8cc42c5..000000000 Binary files a/documentation/how-to/images/adfs_image4.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image5.png b/documentation/how-to/images/adfs_image5.png deleted file mode 100644 index 0b27abfa7..000000000 Binary files a/documentation/how-to/images/adfs_image5.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image6.png b/documentation/how-to/images/adfs_image6.png deleted file mode 100644 index f1b90068d..000000000 Binary files a/documentation/how-to/images/adfs_image6.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image7.png b/documentation/how-to/images/adfs_image7.png deleted file mode 100644 index 2884d0563..000000000 Binary files a/documentation/how-to/images/adfs_image7.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image8.png b/documentation/how-to/images/adfs_image8.png deleted file mode 100644 index 41fd44869..000000000 Binary files a/documentation/how-to/images/adfs_image8.png and /dev/null differ diff --git a/documentation/how-to/images/adfs_image9.png b/documentation/how-to/images/adfs_image9.png deleted file mode 100644 index 1523190f9..000000000 Binary files a/documentation/how-to/images/adfs_image9.png and /dev/null differ diff --git a/documentation/how-to/images/azure_image1.png b/documentation/how-to/images/azure_image1.png deleted file mode 100644 index 5920c3496..000000000 Binary files a/documentation/how-to/images/azure_image1.png and /dev/null differ diff --git a/documentation/how-to/images/azure_image2.png b/documentation/how-to/images/azure_image2.png deleted file mode 100644 index b286b65ac..000000000 Binary files a/documentation/how-to/images/azure_image2.png and /dev/null differ diff --git a/documentation/how-to/images/azure_image3.png b/documentation/how-to/images/azure_image3.png deleted file mode 100644 index 28604b543..000000000 Binary files a/documentation/how-to/images/azure_image3.png and /dev/null differ diff --git a/documentation/how-to/images/azure_image4.png b/documentation/how-to/images/azure_image4.png deleted file mode 100644 index 74d2a7520..000000000 Binary files a/documentation/how-to/images/azure_image4.png and /dev/null differ diff --git a/documentation/how-to/images/azure_image5.png b/documentation/how-to/images/azure_image5.png deleted file mode 100644 index 985950bb0..000000000 Binary files a/documentation/how-to/images/azure_image5.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image1.png b/documentation/how-to/images/ldap_image1.png deleted file mode 100644 index bf9b3e4db..000000000 Binary files a/documentation/how-to/images/ldap_image1.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image2.png b/documentation/how-to/images/ldap_image2.png deleted file mode 100644 index 70e9b1e71..000000000 Binary files a/documentation/how-to/images/ldap_image2.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image3.png b/documentation/how-to/images/ldap_image3.png deleted file mode 100644 index e69c75641..000000000 Binary files a/documentation/how-to/images/ldap_image3.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image4.png b/documentation/how-to/images/ldap_image4.png deleted file mode 100644 index 94a5bc074..000000000 Binary files a/documentation/how-to/images/ldap_image4.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image5.png b/documentation/how-to/images/ldap_image5.png deleted file mode 100644 index b28c368b9..000000000 Binary files a/documentation/how-to/images/ldap_image5.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image6.png b/documentation/how-to/images/ldap_image6.png deleted file mode 100644 index 6957d1b90..000000000 Binary files a/documentation/how-to/images/ldap_image6.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image7.png b/documentation/how-to/images/ldap_image7.png deleted file mode 100644 index b05e8365f..000000000 Binary files a/documentation/how-to/images/ldap_image7.png and /dev/null differ diff --git a/documentation/how-to/images/ldap_image8.png b/documentation/how-to/images/ldap_image8.png deleted file mode 100644 index c200d7e50..000000000 Binary files a/documentation/how-to/images/ldap_image8.png and /dev/null differ diff --git a/documentation/how-to/index.rst b/documentation/how-to/index.rst deleted file mode 100644 index 503e169f7..000000000 --- a/documentation/how-to/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -How-to guides -============= - -These how-to guides cover key operations and processes in JAAS. - -.. toctree:: - :maxdepth: 1 - - Set up Route53 - Deploy JIMM - Deploy JIMM on K8S - Add controller - Deploy Candid - Deploy Candid on K8S - Candid LDAP integration - Candid Azure integration - Candid ADFS integration diff --git a/documentation/how-to/route53.rst b/documentation/how-to/route53.rst deleted file mode 100644 index 50c2c500f..000000000 --- a/documentation/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 hoste 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/documentation/index.rst b/documentation/index.rst deleted file mode 100644 index a11bdb216..000000000 --- a/documentation/index.rst +++ /dev/null @@ -1,70 +0,0 @@ -:relatedlinks: [Diátaxis](https://diataxis.fr/) - -.. _home: - -JAAS Documenation -========================== - -**JAAS** provides a single location to manage your Juju infrastructure by using the -Dashboard or using the same 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 - a 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 - -- Juju controllers - each controlling models in specific clouds or cloud regions. - -- Juju dashboard - providing a clear overview of your Juju real estate with the ability to drill down into details of your deploys - -**JAAS** is useful for customers that do not want to maintain their own controllers -in public clouds taking advantage of our production JAAS giving them the ability to -deploy their workloads in public clouds. JAAS is also useful for organisations -running their own Juju infrastructure giving them a single point of contact for -their entire real estate and, in combination with the Juju Dashboard, giving -them a clear overview of their infrastructure. - ---------- - -In this documentation ---------------------- - -.. grid:: 1 1 2 2 - - .. grid-item:: :doc:`Tutorial ` - - - .. grid-item:: :doc:`How-to guides ` - - -.. grid:: 1 1 2 2 - :reverse: - - .. grid-item:: :doc:`Reference ` - - - .. grid-item:: :doc:`Explanation ` - - ---------- - -Project and community ---------------------- - -Example Project is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. - -* :ref:`Code of conduct ` -* :ref:`Get support ` -* :ref:`Join our online chat ` -* :ref:`Contribute ` - - -.. toctree:: - :hidden: - :maxdepth: 2 - - tutorial/index - how-to/index - reference/index - explanation/index diff --git a/documentation/reference/index.rst b/documentation/reference/index.rst deleted file mode 100644 index d5018eeee..000000000 --- a/documentation/reference/index.rst +++ /dev/null @@ -1,4 +0,0 @@ -Reference -========= - -**Technical information** - specifications, APIs, architecture \ No newline at end of file diff --git a/documentation/reuse/links.txt b/documentation/reuse/links.txt deleted file mode 100644 index fa7df722c..000000000 --- a/documentation/reuse/links.txt +++ /dev/null @@ -1 +0,0 @@ -.. _Canonical website: https://canonical.com/ diff --git a/documentation/tutorial/group_management.rst b/documentation/tutorial/group_management.rst deleted file mode 100644 index 2ebfa92cd..000000000 --- a/documentation/tutorial/group_management.rst +++ /dev/null @@ -1,172 +0,0 @@ -Group and access management -================ - -Introduction ------------- - -JAAS provides group management capabilities, this allows JAAS -administrators to add and remove users to and from groups and -allow or disallow group access to various resources. - -In this tutorial we will show you how to manage groups in JAAS and how to grant -access to those groups. - -Prerequisites -------------- - -For this tutorial you will need the following: - -- Deployed JAAS system (JIMM and Candid) with a few valid users (see :doc:`../how-to/deploy_jimm` and :doc:`../how-to/deploy_candid`) -- At least one controller connected to JIMM (see :doc:`../how-to/add_controller`) -- jimmctl command (either built from source or installed via a snap) - -Group management ----------------- - -For this part of the tutorial we will assume your Candid has been configured -to contain the following users: - -- alice -- adam -- eve - -Next, let us create three groups for these users. Run: - -.. code:: console - - jimmctl auth group add A - jimmctl auth group add B - jimmctl auth group add C - -which will create groups *A*, *B* and *C*. - -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 - -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`). - -Now to make things a bit more interesting we will make group *A* member of -group *B* and group *B* member of group *C* by running: - -.. code:: console - - jimmctl auth relation add group-A#member member group-B - jimmctl auth relation add group-B#member member group-C - -Note the special *group-A#member* notation by which we refer to members of -group *A*. In effect the first of these two commands tells JAAS that all users -that have a *member* relation to group *A* also have a *member* relation to -group *B*. And likewise the second command tells JAAS that all users that -have a *member* relation to group *B* also have a *member* relation to group *C*. - -To list all groups known to JAAS run: - -.. code:: console - - jimmctl group list - -which will show us the three groups we created. - -Let's assume we want to rename group *C* to *D*. To achieve this we run: - -.. code:: console - - jimmctl auth group rename C D - -If we run: - -.. code:: console - - jimmctl group list - -we will see groups *A*, *B* and *D*. - -Renaming a group **does not** affect group membership or any access rights a group -might already have in JAAS. This means that members of groups *A* and *B* are -still members of group *D*. - -To remove group *D* from JAAS, we run: - -.. code:: console - - jimmctl auth group remove D - -And now listing groups will show only groups *A* and *B*. - -Granting access to groups -------------------------- - -Now that we know how to manage groups and group membership let's take a look -at how we can grant groups access to resources in JIMM. Remember that we -will refer to resources by their JAAS tags (for -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* - - 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 -user and the controller by running: - -.. code:: console - - jimmctl auth relation add user-eve 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 -manage deployed applications. To achieve this run: - -.. code:: console - - jimmctl auth relation add group-A#members writer model-test-ctl-1/test-model-1 - -And finally let us give members of group *B* consume permission on the created -application offer by running: - -.. code:: console - - 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 -by running: - -.. code:: console - - jimmctl auth relation check user-adam 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 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 - -Running: - -.. code:: console - - jimmctl auth relation check user-adam consumer applicationoffer-test-ctl-1/test-model-1.postgresql-db - -we will see user *adam* no longer has access to the application offer. - -Conclusion ----------- - -This tutorial taught you the basics of group and access management in JAAS. - diff --git a/documentation/tutorial/images/jaas_image1.png b/documentation/tutorial/images/jaas_image1.png deleted file mode 100644 index cb89b879b..000000000 Binary files a/documentation/tutorial/images/jaas_image1.png and /dev/null differ diff --git a/documentation/tutorial/images/jaas_image2.png b/documentation/tutorial/images/jaas_image2.png deleted file mode 100644 index 8ce47cc6c..000000000 Binary files a/documentation/tutorial/images/jaas_image2.png and /dev/null differ diff --git a/documentation/tutorial/index.rst b/documentation/tutorial/index.rst deleted file mode 100644 index d9e4e8766..000000000 --- a/documentation/tutorial/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Tutorials -============= - -This is a collection of tutorials covering JAAS. - -.. toctree:: - :maxdepth: 1 - - JAAS Basics - Group and access management diff --git a/documentation/tutorial/jaas_basics.rst b/documentation/tutorial/jaas_basics.rst deleted file mode 100644 index 42b9ba3a6..000000000 --- a/documentation/tutorial/jaas_basics.rst +++ /dev/null @@ -1,391 +0,0 @@ -JAAS Basics -=========== - - -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 synchronized 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`` - -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.