How to authenticate Charmcraft in remote environments

charmcraft
1

Introduced in Charmcraft 1.3

When working locally with Charmcraft, the developer will use charmcraft login to get authentication tokens from Charmhub, which would be stored in the local keyring and used on all operations that need them.

This is fine for local environments, but for remote ones (e.g. a CI/CD system) on one hand it’s desirable to not login using the standard method (a browser opening an authentication web page to insert user, password, and 2FA), and on the other hand the authentication tokens should be limited in different ways.

The alternative login method is implemented through the CHARMCRAFT_AUTH environment variable, which needs to be set to useful credentials (which are obtained using the --export option, see below).

If that variable is set Charmcraft will use it for all operations that needs authentication against Charmhub. Note that in this case the login and logout commands can not be used.

To obtain credentials to be used in CHARMCRAFT_AUTH, the login command has the --export option, which accepts a file path. If specified, it will override the regular behaviour of storing the credentials in the user’s keyring, and those will be exported to the given file path. The content of this file is what should be used verbatim in the environment variable.

As mentioned at the beginning, it’s also a good idea to use restricted credentials in a remote system. For this situation, the Charmcraft’s login command provides different options to attenuate the obtained authentication tokens:

  • --charm: the charm name on which the permission will apply (can be specified multiple times)
  • --bundle: the bundle name on which the permission will apply (can be specified multiple times)
  • --permission: what action can be done on the specified package(s) (see below for a list; can be specified multiple times)
  • --channel: the channel on which the package can be released (can be specified multiple times)
  • --ttl: the time, in seconds, that the granted token will be useful (defaults to 30 days)

All these indications are optional, and default to no restrictions applied on each category (except indicated the time-to-live, as indicated above). Note also that these restrictions can only be used if the credentials are exported to a file with the --export option.

The available permissions are:

  • account-register-package: register/request a new package name
  • account-view-packages: list packages owned by the account or for which this account has collaborator rights
  • package-manage: meta permission that includes all the package-manage-* ones
  • package-manage-acl: add/invite/remove collaborators
  • package-manage-metadata: edit metadata, add/remove media, etc.
  • package-manage-releases: release revisions and close channels
  • package-manage-revisions: upload new blobs, check for upload status
  • package-view: meta permission that includes all the package-view-* ones
  • package-view-acl: list the collaborators for a package, return privacy settings
  • package-view-metadata: view the metadata for a package, including media
  • package-view-metrics: view the metrics of a package
  • package-view-releases: list the current releases (channel map) and the history of releases for a package
  • package-view-revisions: list the existing revisions for a package, along with status information

So, an example sequence for requesting/using credentials to set up a CI/CD system that will push and release a charm could be:

  • get the specific credentials in a file:

    $ charmcraft login --export=secrets.auth --charm=my-super-charm --permission=package-manage --channel=edge --ttl=2592000
Login successful. Credentials exported to 'secrets.auth'.

  • test that all is fine; for this get the content:

    $ CHARMCRAFT_AUTH=`cat test1` charmcraft whoami
name: J. Doe
username: jdoe-superdev
id: VTLZAToLcdaIPtisVBjfiQYCXbpKwbCc
charms:
- my-super-charm
permissions:
- package-manage
channels:
- edge
time to live (s): 2592000

  • to use this authorization token on a CI/CD system set the environment variable CHARMCRAFT_AUTH with the content of secrets.auth file, and use Charmcraft as normal:

    export CHARMCRAFT_AUTH=<a long chunk of chars>
...
charmcraft upload my-super-charm.charm --release edge
3 Likes
2

I would rewrite:

to

to use this authorization token on a CI/CD system set the environment variable CHARMCRAFT_AUTH with the content of secrets.auth file, and use Charmcraft as normal:

If the environment variable is already exported through a CI/CD primitive this line is not needed:

1 Like
3

Something to clarify is if we would allow these options without --export

4

Yes. They are orthogonal. Do you want me to make this explicit in the text?

5

Perhaps yes, in the sense that you might be limited in your common use of charmcraft if you don’t have all the permissions

6

Which may be desirable… don’t know.

Anyway, I don’t have a position here, so please decide what you prefer and I’ll adjust the spec.

7

That’s great news!

I have some questions about the permissions:

  • which are the ones necessary to upload charm resources? If my CI uploads a charm that has a resource attached, do I need extra permissions to “link” the new revision to the previous resource? Is is possible to charmcraft upload needs_resource.charm --use-latest-resource?
  • is it necessary to have an extra permission to manage charm libraries?
1 Like
8