Add credentials

In order for Juju to be able to create and manipulate resources on the underlying cloud, it needs to be provided with a credential that has an appropriate set of permissions associated with it. Depending on the cloud substrate, the credential will take the form of a username/password pair, a secret key, or a certificate.

Upon adding a new credential to Juju, users are asked to provide an alias name which is subsequently used to refer to the stored credential. Credentials may be added to the local client, the currently active controller (if any), or both.

Credentials become active as soon as they are related to a Juju model. Typically, this is facilitated via the bootstrap and add-model commands, as both trigger the creation of a new model.

Add credentials

Juju supports three methods for adding credentials:

  • Manually providing credentials via an interactive session with the command line client.
  • Auto-detecting credentials by scanning environment variables and/or “rc” files (only supported for certain providers).
  • Importing credentials from a user-provided, YAML-formatted file.

A local LXD cloud is a special case. When accessed from a Juju admin user, a credential does not need to be added—a 10-yr certificate is automatically set up for you. However, when accessed from a non-admin user, this is not the case. See Additional LXD resources for details.

The Juju client stores any added credentials into $HOME/.local/share/juju/credentials.yaml.

Use the interactive method

The add-credential command can be used to add credentials via an interactive session. For example, to add a credential for an AWS cloud:

juju add-credential aws

Note that credentials can be added to the local client, the currently active controller, or both. The interactive session will display a prompt asking you to select the preferred location for storing the credentials:

This operation can be applied to both a copy on this client and to the one on a controller.
Do you want to add a credential to:
    1. client only (--client)
    2. controller "test" only (--controller mycontroller)
    3. both (--client --controller mycontroller)
Enter your choice, or type Q|q to quit:

Depending on the selected cloud type, the interactive session will then ask a set of questions to collect all the required information for accessing that particular cloud. For instance, the interactive session for adding an AWS credential looks as follows:

Enter credential name: carol

Using auth-type "access-key".

Enter access-key: AKBAICUYUPFXID2GHC5S

Enter secret-key:

Credential "carol" added locally for cloud "aws".

The Juju client allows multiple credentials to be registered for the same cloud. In this case, one of them must be selected as the default. For more information on selecting the default credential for a cloud, consult the instructions in the Setting the default credential for a cloud section.

Use the auto-detection method

A common pattern used by the set of command line tools that many cloud providers offer as part of their software development kits (SDKs) is to allow users to specify their credentials either via environment variables or via files (colloquially known as “rc” files) that are stored in known, predefined locations.

Juju can auto-detect credentials defined in this fashion for Amazon AWS, Google GCE, and OpenStack using the autoload-credentials command:

juju autoload-credentials

When the above command is executed, Juju will scan the environment variables and, for each detected credential, display a prompt asking you to confirm the addition of the credential and to specify a name for it.

If the cloud credential ever changes, the above process will need to be repeated so that Juju can pick up the updated credential.

Finally, the autoload-credentials command may also be used to generate a certificate for local LXD clouds; this is a requirement when providing access to non-admin Juju users. See Additional LXD resources.

Use a YAML file

YAML-formatted files provide a way for bulk-importing credentials for one or more clouds. In the YAML file below (mycreds.yaml) you can see an example of how one can specify credentials for several of the cloud types supported by Juju.

Expand YAML file
credentials:
  aws:
    peter:
      auth-type: access-key
      access-key: AKIAIH7SUFMBP455BSQ
      secret-key: HEg5Y1DuGabiLt72LyCLkKnOw+NZkgszh3qIZbWv
    jlaurin:
      auth-type: access-key
      access-key: AKIAIFII8EH5BOCYSJMA
      secret-key: WXg6S5Y1DvwuGt72LwzLKnItt+GRwlkn668sXHqq
  homemaas: # a MAAS cloud
    peter:
      auth-type: oauth1
      maas-oauth: 5weWAsjhe9lnaLKHERNSlke320ah9naldIHnrelks
  myopenstack: # an OpenStack instance
    john:
      auth-type: access-key
      access-key: bae7651caeab41ed876cfdb342bae23e
      secret-key: 7172bc91a21c3df1787423ac12093bcc
      tenant-name: admin
      username: admin   
  homestack: # another Openstack instance
    peter:
      auth-type: userpass
      password: UberPassK3yz
      tenant-name: appserver
      username: peter
  google:
    peter:
      auth-type: jsonfile
      file: ~/.config/gcloud/application_default_credentials.json
    juju-gce-1-sa:
      auth-type: oauth2
      project-id: juju-gce-1
      private-key: |
        -----BEGIN PRIVATE KEY-----
        MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCzTFMj0/GvhrcZ
        3B2584ZdDdsnVuHb7OYo8eqXVLYzXEkby0TMu2gM81LdGp6AeeB3nu5zwAf71YyP
        erF4s0falNPIyRjDGYV1wWR+mRTbVjYUd/Vuy+KyP0u8UwkktwkP4OFR270/HFOl
        Kc0rzflag8zdKzRhi7U1dlgkchbkrio148vdaoZZo67nxFVF2IY52I2qGW8VFdid
        z+B9pTu2ZQKVeEpTVe5XEs3y2Y4zt2DCNu3rJi95AY4VDgVJ5f1rnWf7BwZPeuvp
        0mXLKzcvD31wEcdE6oAaGu0x0UzKvEB1mR1pPwP6qMHdiJXzkiM9DYylrMzuGL/h
        VAYjhFQnAgMBAAECggEADTkKkJ10bEt1FjuJ5BYCyYelRLUMALO4RzpZrXUArHz/
        CN7oYTWykL68VIE+dNJU+Yo6ot99anC8GWclAdyTs5nYnJNbRItafYd+3JwRhU0W
        vYYZqMtXs2mNMYOC+YNkibIKxYZJ4joGksTboRvJne4TN7Et/1uirr+GtLPn+W/e
        umXfkpbOTDDAED8ceKKApAn6kLIW98DwHyK0rUzorOgp4DFDX9CjuWC+RG3CFGsk
        oVOcDuTevJlb9Rowj1S2qYhGjuQVpVD7bcRg5zaSJKS88YbK63DCHZFpXn9JR0Fg
        Vou9dnc99FdMo5vtHg7Adxh91gdqEvoaF1lHx8Var0q32QDse+spvv7K6/+7G35k
        3+1gDgF74/uMr/AVrjpoUjmGAuWweXY/vn1MVN2Uld4KPYafkOF8oTuDK5f1fu0d
        cMEoKRSXQh1NCD3PZWfQt4ypYPzn9R+VBGwnBcPorytlhM9qdLxKKlaHjBlprS6Y
        Be1z6FO+MqWhFlwPrKH/2uwd4QKBgQDCGESJur9OdEeroBQyYyJF7DnJ/+wHSiOr
        qzvb9YW1Ddtg1iiKHHZO5FS59/D62kPaGsysCMKxI9FW53TzSxUiTaEG636C5v8J
        eRdzxX04BNYNzqXbm1agBEjAa7tK8xJAjk0to4zqadUaYZog0uQs2X7Aexj2c9T/
        HQVLILHjBwKBgD/yuoLNbST+cGbuZl1s2EnTP796xPkkUm3qcUzofzmn6uivz7Qp
        FMThZhHZ/Der98tra91a4e8fHaUTL5d4eCMeCL1mWXoNMnm02D/ugpEC8yDefi3T
        xlM/Ed0IEVogcd49tvTvQfrhfbW/6Que/rkLKCoUlAldfIOYkS4YyyTBAoGACCpH
        L9gYVi+UGEc6skfzWCew4quOfVwEFiO09/LjNhOoJ/G6cNzzqSv32H7yt0rZUeKQ
        u6f+sL8F/nbsN5PwBqpnXMgpYU5gakCa2Pb05pdlfd00owFs6nxjpxyhG20QVoDm
        BEZ+FhpvqZVzi2/zw2M+7s/+49dJnZXV9Cwi758CgYAquNdD4RXU96Y2OjTlOSvM
        THR/zY6IPeO+kCwmBLiQC3cv59gaeOp1a93Mnapet7a2/WZPL2Al7zwnvZYsHc4z
        nu1acd6D7H/9bb1YPHMNWITfCSNXerJ2idI689ShYjR2sTcDgiOQCzx+dwL9agaC
        WKjypRHpiAMFbFqPT6W2uA==
        -----END PRIVATE KEY-----
      client-id: "206517233375074786882"
      client-email: juju-gce-sa@juju-gce-123.iam.gserviceaccount.com
  azure:
    peter:
      auth-type: service-principal-secret
      application-id: c07fd75f-dc07-47a1-87ed-123456731897
      subscription-id: bef58c0a-6fca-489d-8297-12345677f276
      application-password: 76ab0f15-4d2e-4dd8-abca-1234567325d5
  oracle:
    jlarin:
      auth-type: httpsig
      fingerprint: a3:57:81:9c:d2:d5:af:31:3b:73:1e:2b:a4:ae:96:ee
      key: |
        -----BEGIN RSA PRIVATE KEY-----
        Proc-Type: 4,ENCRYPTED
        DEK-Info: AES-128-CBC,AAAC919B21A2694027DBEB182593FBEC

        MIIEogIBAAKCAQEAoc9jtcvo49FWe3sOhS6c1ExkllNZ61vChsLmMhBCI1vMc8wu
        cMpNmYK1ZA+d2Mm5YWDwn4UrSTzyaFdAIesmRljfbYMGTLznI/nfQMa1hkmplF5Q
        xNPCdzs0afqfnubIyrvCKYfAsRzjCcs7C30n6PzG5WrKxzr1QNvAuvYgjd2oQuSY
        nAhDgdJDkA9UwJFgI1jE8EuoxjkvmyeL76ohe78IEjMzoBBvll/Vd3d8X/hCHt4b
        wkmn3B5+QzXIvYXGhaUoZrmG6V+tsk2H5voJj6TswDB8rqIa1SHbY81wIkMUxbD4
        ScAq8eq2/6ETXcoBULKCjmvyqekJHjT7NngbpwIDAQABAoIBAEEggheIDSK0/UQS
        EZQVYNYqMUo4HjcW5cL/PRvlY1lr92ycQAzxwC4LaArwJi49czn4lKEALp35w++v
        PoboaK1j0/n2BLEaT0YxqmQeFq4INBMdqxCt0tW+pKgLUffZF/RRgiLJGwuufstQ
        W2GSbF/gbgWk6B0sY85JJNebfRrb+qjp5Jz+5t5gNVzOwWWkPYoAKXPd9JHYPFAk
        JCUTloYdf16lBml+nZI7EGojXtHUpdF7KyYRVfXMfxBnaWpVHvoZBk5Vk5qL/boz
        N8W+YahFq9BELavYQ30CZQeWYoD2MaSCWv+WzfkER8YK5Onr+5CSU0lW9dqN6wuv
        LFozUgECgYEAy9vZb+hjn3otkEFvyCGg9wmGIs9Qro3UKJI/mGKQeL7K8sd5WsA6
        mbOkIDbK71ZG+iIfxDXLzRO1ZzPjAX3cReFZ9NFRHngX9xM92UP+icIJkM6m4ImN
        UcaGCZiF0LoKUTAkEw+5rpeudGcgNgaI41RKMUBLyQn5MFo3IAPaO4ECgYEAyzJN
        CqB4e+qJgmc29zKsSfvuofasDTmIMnOZW2ci+tiD/qiH/eJoKHK2F5yGV6/tB2iY
        kFSuzWEwu/Crl7seW6xPY+HYlGLD60ix1aRDEfR48bZqFqlIu7uowI9dp43aOmPU
        1YSgMj8UA+rVqHqrS6IX4iqGbEOuzq0a377qiycCgYA99oUQzsH5J1nSDxG68v3K
        GMr8qacMZ2+lJU7PMqZXDScCxD7Opr8pGME6SW1FciQAw36EVRWtL+BjjhBcw7TA
        SM7e6wCNElO4ddLGxzQHC0N9EFMIzMZ3pK/5arMRznp0Uv2kDZOSzefo2a+gvDu/
        XU9vyOtAIBft6n327TTYAQKBgEE3/OhbRzCmv8oeLNM87XW1qgtMLD72Z1OiLOfc
        e6q90efr2fJQOBQ7dVywvaHpco+9L7Krq4vWlXjdL4ZCCJVuAfFSLPy7kpyzMXkc
        Bvb9W9BiNz3cyd6PxdDTQFhNwbXdE2QQ9IYMHvV+62LvNInLFhVehtS7CKGHiCem
        lItJAoGAdnj8nJRFQCAyIGcYk6bloohXI8ko0KLYbHfQpN9oiZa+5crEMzcFiJnR
        X8rWVPCLZK5gJ56CnP8Iyoqah/hpxTUZoSaJnBb/xa7PCiMq1gBfSF8OYlCsRI0V
        semYTOymUHkZyWGMIhmdn6t1S9sOy2tYjiH6HqumwirxnD5CLDk=
        -----END RSA PRIVATE KEY-----
      pass-phrase: "ChimayBlue"
      tenancy: ocid1.tenancy.oc1..aaaaaaaanoslu5x9e50gvq3mdilr5lzjz4imiwj3ale4s3qyivi5liw6hcia
      user: ocid1.user.oc1..aaaaaaaaizcm5ljvk624qa4ue1i8vx043brrs27656sztwqy5twrplckzghq
  vsphere:
    ashley:
      auth-type: userpass
      password: passw0rd
      user: administrator@xyz.com
  lxd-node2:
    interactive:
      auth-type: interactive
      trust-password: ubuntu

Note that credentials are added to Juju on a per-cloud basis. For instance, the following command can be used to import the credentials for the azure cloud as defined in the above file:

juju add-credential azure -f mycreds.yaml

Manage credentials

Set the default credential for a cloud

The set-default-credential command allows you to select the default credential for a particular cloud. For example, the following command sets the credential named carol as the default credential for the aws cloud:

juju set-default-credential aws carol

Some Juju commands (bootstrap, add-model etc.) require a suitable cloud credential to be specified. If only a single credential is defined for a particular cloud, it becomes the effective default credential for that cloud and will be automatically used by the aforementioned commands.

However, when multiple credentials are defined, you will need to either set a default one (following the steps above) or manually specify the name of the credential to be used for each Juju command via the --credential flag. Failure to do so will cause the Juju client to emit an error:

ERROR more than one credential is available
specify a credential using the --credential argument

List credentials

A list of the available credentials be obtained by running the credentials command:

juju credentials

Sample output:

Controller Credentials:
Cloud           Credentials
lxd             localhost

Client Credentials:
Cloud   Credentials
aws     bob*, carol
google  wayne

In the above output, asterisks denote the default credential for a cloud. Here, the credential named bob is the default for cloud aws and no default has been specified for the lxd and google clouds.

By default, the command output groups credentials into two sets:

  • Credentials that are available to the currently active controller.
  • Credentials that are available to the local Juju client.

To display only the credentials available to the local Juju client, specify the --client flag when invoking the credentials command. Likewise, to limit the displayed credentials to the ones stored in a particular controller you can instead specify the --controller flag followed by the controller’s name when invoking the command.

To same command can also be used to display the actual credential contents when the --show-secrets flag is specified :

juju credentials --client --format yaml --show-secrets

Sample output:

local-credentials:
  aws:
    bob:
      auth-type: access-key
      access-key: AKIAXZUYGB6UED2GNC5A
      secret-key: StB2bmL1+tX+VX7neVgy/3JosJAwOcBIO53nyCVp

Update credentials

The update-credential command can be used to update an existing credential either interactively or by reading the contents of a YAML file.

The command behaves in the same fashion as the other credential-related commands; when the command is run, the Juju client will prompt you to select whether you want to update the credential stored in the local client, the currently active controller or both.

For example, the following command will read the mycreds.yaml file from the previous section and update the credentials for the aws cloud:

juju update-credential aws -f mycreds.yaml

Juju will first read the credentials from the provided file and then proceed to overwrite the contents of any existing credentials for the specified cloud (aws in this example) whose names match the ones in the file.

If you wish to update the credential either for the local Juju client or the active controller, you can include the --client or the --controller flags when running the above command.

In this case, the prompt for selecting the target for the update operation will be bypassed.

When updating a credential stored in a controller, Juju first runs a set of sanity checks to ensure that the new credential contents can authenticate with the backing cloud and that any machines that may reside within a model currently related to the credential remain accessible.

These tests can be bypassed by running the update-credentials command with the --force flag.

Remove credentials

The remove-credential command is used to remove existing credentials from the local Juju client, the currently active controller or both. For example, the following command will remove the credential named bob from the aws cloud:

juju remove-credential aws bob

As with all other credential-related commands, unless the --client or --controller flags are specified, the Juju client will first display a prompt asking you to select where the credential is to be removed from.

When opting to remove a credential stored in a controller, Juju will first check whether any other model hosted by the controller is currently using that credential and display an error if that’s the case:

ERROR could not remove remote credential: cannot revoke credential cloudcred-aws_admin_bob: it is still used by 2 models

However, the above check can be effectively bypassed if the --force flag is specified when running the remove-credential command.

Relate a credential to a model

Controller admins and model owners can leverage the set-credential command to relate a credential to a model. Note that the credential to be related may be already uploaded to the controller (e.g. another model might be related to it) or may be stored in the local client. In the latter case, the credential will be first uploaded to the controller.

For example, the following command will relate a credential named bob for the aws cloud to an existing model called trinity:

juju set-credential -m trinity aws bob

This command does not affect any existing relations between the credential and other models. If the credential is already related to a single model, this operation will simply cause the credential to be related to two models.

When a model is added to the controller via the add-model command, you can select which credential will be related to the new model. In addition, the Juju client also supports changing the related credential for an existing model via the set-credential command as outlined in the previous section.

The show-model command allows you to query the name of the credential related to a particular model. For instance, to identify the credential used by a model called example:

juju show-model example

Partial output:

test:
  name: admin/example
  ...
  ...
  credential:
    name: bob
    owner: admin
    cloud: aws

Next steps

The Managing credentials tutorial explores these commands in more depth and also includes useful hints and tips for dealing with various credential-related issues.


Last updated 23 days ago.