diff --git a/how-to/add_controller.rst b/how-to/add_controller.rst index b66d3f6..e1a0ec7 100644 --- a/how-to/add_controller.rst +++ b/how-to/add_controller.rst @@ -46,7 +46,7 @@ Deploy controller +----------------------+----------------------+ | Parameter | Environment variable | +======================+======================+ - | Controller nam | $NAME | + | Controller name | $NAME | +----------------------+----------------------+ | Cloud | $CLOUD | +----------------------+----------------------+ diff --git a/how-to/add_controller_no_dns.rst b/how-to/add_controller_no_dns.rst index 1238966..9cfe805 100644 --- a/how-to/add_controller_no_dns.rst +++ b/how-to/add_controller_no_dns.rst @@ -7,7 +7,7 @@ Introduction The :doc:`add_controller` doc is a full guide on how to setup a controller, provide it with a load balancer front-end and use the load-balancer to terminate TLS connections. This guide provides a simplified setup that shows how to get a controller up and running with JIMM without the need for a load-balancer and a DNS address. -This guide is intended for testing and development purposes only as the Juju controller cannot be created in an HA (high availability) setup. +This guide is intended for testing and development purposes only as the Juju controller cannot be created in an HA (high-availability) setup. Prerequisites ------------- @@ -16,27 +16,27 @@ For this tutorial you will need the following: - AWS credentials - Basic knowledge of juju -- Admin access to a JIMM controller (see this tutorial). For this tutorial we will assume this JIMM is located at jimm.canonical.example.com +- 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 **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 **Candid URL** is the URL of the candid server that is providing the centralized identity service for the JAAS system. + The **Candid URL** is the URL of the candid server that is providing the centralised 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 | + | Controller name | $NAME | +----------------------+----------------------+ | Cloud | $CLOUD | +----------------------+----------------------+ @@ -56,12 +56,10 @@ Deploy controller ``juju switch controller`` -4. Install the jaas snap that you download here (note that this will eventually change to be accessible from https://snapcraft.io/jimmctl): - - https://drive.google.com/file/d/1LiOvVpVQ13V3x3l2PhgS2fTHDUtCEe7p/view?usp=sharing +4. Install the JAAS snap that you download from `here `_ (note that this will eventually change to be accessible from ``https://snapcraft.io/jimmctl``). 5. To add the bootstrapped controller to JIMM we need to create a controller-information document. To do this, run the following command: - The "--local" flag allows you to skip providing the DNS address of your Juju controller. + The ``--local`` flag allows you to skip providing the DNS address of your Juju controller. ``/snap/jaas/current/bin/jimmctl controller-info --local $NAME $NAME.yaml`` @@ -73,4 +71,6 @@ Deploy controller ``/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 +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/how-to/use_terraform.rst b/how-to/use_terraform.rst index af128ec..34da34f 100644 --- a/how-to/use_terraform.rst +++ b/how-to/use_terraform.rst @@ -11,13 +11,13 @@ Prerequisites For this how-to you will need the following: -- An identity provider that can be used to create OAuth2 client credentials -- Client credentials (`client_id` and `client_secret`) generated by the above identity provider. +- An identity provider that can be used to create OAuth2 client credentials. +- Client credentials (``client_id`` and ``client_secret``) generated by the above identity provider. - A deployed JIMM configured to trust the identity provider. For instructions on how to deploy JIMM read :doc:`deploy_jimm`. - A Juju 3.5 controller added to JIMM that can be used to control your chosen cloud. For instructions on how to add one read :doc:`add_controller`. -- A Juju 3.5 client +- A Juju 3.5 client. - Cloud credentials for the chosen cloud (see `here `_). - Basic knowledge of Terraform, Juju Terraform provider and Juju. @@ -44,11 +44,11 @@ Juju Terraform provider ----------------------- To authenticate with JIMM the provider section in your Terraform plan needs to include -the `client_id` and `client_secret` generated by your identity provider. Please note that +the ``client_id`` and ``client_secret`` generated by your identity provider. Please note that you need to use a version of the `Juju Terraform provider `_ -higher than `0.12.0`. +higher than ``0.12.0``. -For this how-to we will be deploying the `juju-qa-test` charm. +For this how-to we will be deploying the ``juju-qa-test`` charm. Let's create a temporary folder. Run: @@ -58,7 +58,7 @@ and: ``cd terraform_tutorial`` -Now create a file called `main.tf` with the following content: +Now create a file called ``main.tf`` with the following content: .. code:: @@ -113,7 +113,7 @@ and verify the proposed changes and run: ``terraform apply`` -You can now switch to the created `qa` model and see the deployed `qa` application. +You can now switch to the created ``qa`` model and see the deployed ``qa`` application. .. code:: diff --git a/reference/audit_logs.rst b/reference/audit_logs.rst index bcd2aa6..64fb96e 100644 --- a/reference/audit_logs.rst +++ b/reference/audit_logs.rst @@ -8,7 +8,7 @@ JIMM provides audit logging functionality, tracking all requests/responses into This gives administrators of JIMM the ability to audit changes at a very granular level. All requests to controllers and models are logged and can enable an analysis into why the state -of the underyling Juju estate has changed. +of the underlying Juju estate has changed. Audit logs are currently enabled by default without any config to disable their collection. The logging retention period is configurable and allows for audit logs to be stored for a @@ -39,23 +39,23 @@ The results can be filtered and paginated as described below. Each audit log contains the following information: -- **time [time]**: When the audit log was created. -- **conversation-id [string]**: A unique id per websocket connection. -- **message-id [uin64]**: An incrementing count for each message sent during a session. -- **facade-name [string]**: The name of the grouping of methods a call is intended for, a facade categorises methods. -- **facade-method [string]**: The name of the method called. -- **facade-version [int]**: The version of the facade called, different client versions may use different facade version. -- **object-id [string]**: A parameter used in some methods, indicates the object being acted upon. -- **user-tag [string]**: The user making the request. -- **model [string]**: The model a request is acting on, can be empty for controller level requests. -- **is-response [boolean]**: Indicates whether this log is for a request or response message. -- **params [map[string]]**: Populated during requests with any request parameters. -- **errors [map[string]]**: Populated during responses with any response errors. +- ``time`` [``time``]: When the audit log was created. +- ``conversation-id`` [``string``]: A unique id per Websocket connection. +- ``message-id`` [``uint64``]: An incremental count for each message sent during a session. +- ``facade-name`` [``string``]: The name of the grouping of methods a call is intended for, a facade categorises methods. +- ``facade-method`` [``string``]: The name of the method called. +- ``facade-version`` [``int``]: The version of the facade called, different client versions may use different facade version. +- ``object-id`` [``string``]: A parameter used in some methods, indicates the object being acted upon. +- ``user-tag`` [``string``]: The user making the request. +- ``model`` [``string``]: The model a request is acting on, can be empty for controller level requests. +- ``is-response`` [``boolean``]: Indicates whether this log is for a request or response message. +- ``params`` [``map[string]``]: Populated during requests with any request parameters. +- ``errors`` [``map[string]``]: Populated during responses with any response errors. It's important to note that JIMM logs requests and responses separately and understanding how to associate a request with a response is a useful tool. This can be done using the `conversation-id` and `message-id` fields. When a client establishes a connection with JIMM and begins making requests, a unique `conversation-id` is generated for -the lifetime of that websocket connection and each request/response pair will have the same `message-id`, which itself will +the lifetime of that Websocket connection and each request/response pair will have the same `message-id`, which itself will increment whenever a new request is made. Then observing the `is-response` and `errors` fields, one can ascertain whether a call was successful. @@ -156,9 +156,9 @@ Filter logs by method call. ``--method`` display events for a specific method call -Each Juju/jimmctl call invokes a specific method. This can be thought of as an HTTP handler. +Each ``juju``/``jimmctl`` call invokes a specific method. This can be thought of as an HTTP handler. Although a full list of all methods is not currently available, it is possible to filter audit events based -on the method that was called. Important methods include Login, Deploy, DestroyApplication, DestroyModels +on the method that was called. Important methods include ``Login``, ``Deploy``, ``DestroyApplication``, ``DestroyModels``. Note that method names are case sensitive. @@ -241,7 +241,7 @@ Purge Logs It is also possible to manually purge audit-logs. -This can be done with the jimmctl CLI and again only JIMM admins have rights to purge audit logs. In this case, +This can be done with the ``jimmctl`` CLI and again only JIMM admins have rights to purge audit logs. In this case, other users cannot be granted this permission. ``jimmctl purge-audit-logs `` @@ -249,7 +249,7 @@ other users cannot be granted this permission. This command will purge audit logs from the database before the given date. Note that the date format is flexible, accepting both a date or date and time. -Note that ommiting the date will assume zero for the time, i.e. the start of that day. +Note that omitting the date will assume zero for the time, i.e. the start of that day. Examples::