Charmcraft

https://documentation.ubuntu.com/charmcraft/stable/
Admin
Charmcraft is the command-line tool for initializing, packaging, and publishing Juju charms for...
Tokens:105,643
Snippets:1,592
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Project Directory and Virtual Environment

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Creates a new directory for the project, navigates into it, installs python3-venv, and creates a Python virtual environment.

```bash
mkdir flask-hello-world
cd flask-hello-world
sudo apt update && sudo apt install python3-venv -y
python3 -m venv .venv
source .venv/bin/activate

```

--------------------------------

### Example Build-Time Operating System

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

An example specifying Ubuntu development series as the build environment.

```yaml
base: ubuntu@devel
```

--------------------------------

### Install Build Snaps

Source: https://documentation.ubuntu.com/charmcraft/stable/common/craft-parts/reference/part_properties

List snaps to install in the build environment before the build starts. Supports formats like '<snap-name>', '<snap-name>/<channel-name>', or '<snap-name>/<channel-name>/<version-name>'. Defaults to 'latest/stable' if channel/version are omitted.

```yaml
build-snaps:
  - go/latest/stable
  - node/stable

```

--------------------------------

### Setup Project Directory and Virtual Environment

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Creates a project directory, navigates into it, installs python-venv, and creates a Python virtual environment. This isolates project dependencies.

```bash
mkdir fastapi-hello-world
cd fastapi-hello-world
sudo apt update && sudo apt install python3-venv -y
python3 -m venv .venv
source .venv/bin/activate

```

--------------------------------

### Install Build Packages

Source: https://documentation.ubuntu.com/charmcraft/stable/common/craft-parts/reference/part_properties

List packages to install in the build environment using the host's native package manager before the build starts. Must be listed by their host system name.

```yaml
build-packages:
  - git
  - libffi-dev
  - libssl-dev

```

--------------------------------

### Example Charm Library Path

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/libname-py-file

Provides a concrete example of the file path for a specific charm library.

```text
lib/charms/mysql/v3/db.py
```

--------------------------------

### Configure UV Plugin with Build Snap

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/plugins/uv_plugin

Example of a project file demonstrating how to use the uv plugin with the astral-uv snap for dependency management. This setup is suitable for Ubuntu 24.04 base.

```yaml
name: my-charm
type: charm
title: My uv charm
summary: An operator charm using uv.
description: |
  An operator charm that uses uv for its project.
base: ubuntu@24.04
platforms:
  amd64:
parts:
  my-charm:
    source: .
    plugin: uv
    build-snaps:
      - astral-uv

```

--------------------------------

### Initiate Charm Packing Process

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Execute this command to start the process of packing a charm. It may prompt for Multipass installation if not already present.

```bash
$ charmcraft pack

```

--------------------------------

### Setup Python Virtual Environment

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Installs `python3-venv` and creates/activates a virtual environment. This isolates project dependencies.

```bash
sudo apt update && sudo apt install python3-venv -y
python3 -m venv .venv
source .venv/bin/activate

```

--------------------------------

### Charmcraft Configuration Example

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

An example of the top section of a charmcraft.yaml file, showing project name, type, base, and platforms.

```yaml
# This file configures Charmcraft.
# See https://juju.is/docs/sdk/charmcraft-config for guidance.

name: go-hello-world

type: charm

base: ubuntu@24.04

# the platforms this charm should be built on and run on.
# you can check your architecture with `dpkg --print-architecture`
platforms:
  amd64:
  # arm64:
  # ppc64el:
  # s390x:


```

--------------------------------

### Example charm-libs Configuration

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/commands/fetch-libs

This example shows how to configure the `charm-libs` key in `charmcraft.yaml` to specify which libraries to fetch. It demonstrates fetching a library with a specific API version and another with an exact version.

```yaml
charm-libs:
# Fetch lib with API version 0.
# If `fetch-libs` is run and a newer minor version is available,
# it will be fetched from the store.
- lib: postgresql.postgres_client
  version: "0"
# Always fetch precisely version 0.57.
- lib: mysql.client
  version: "0.57"

```

--------------------------------

### Example Charm Packing Session

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charms

This example shows the output of `charmcraft pack` and subsequent commands to verify the packed charm and its contents.

```bash
charmcraft pack

```

```text
Created 'microsample-vm_ubuntu-22.04-amd64.charm'.
Charms packed:
  microsample-vm_ubuntu-22.04-amd64.charm


```

```bash
ls

```

```text
CONTRIBUTING.md  charmcraft.yaml                          requirements.txt  tox.ini
LICENSE          microsample-vm_ubuntu-22.04-amd64.charm  src
README.md        pyproject.toml                           tests


```

```bash
unzip -l microsample-vm_ubuntu-22.04-amd64.charm | { head; tail;}

```

```text
Archive:  microsample-vm_ubuntu-22.04-amd64.charm
  Length      Date    Time    Name
---------  ---------- -----   ----
      815  2023-12-05 12:12   README.md
    11337  2023-12-05 12:12   LICENSE
      250  2023-12-05 12:31   manifest.yaml
      102  2023-12-05 12:31   dispatch
      106  2023-12-01 14:59   config.yaml
      717  2023-12-05 12:31   metadata.yaml
      921  2023-12-05 12:26   src/charm.py
      817  2023-12-01 14:44   venv/setuptools/command/__pycache__/upload.cpython-310.pyc
    65175  2023-12-01 14:44   venv/setuptools/command/__pycache__/easy_install.cpython-310.pyc
     4540  2023-12-01 14:44   venv/setuptools/command/__pycache__/py36compat.cpython-310.pyc
     1593  2023-12-01 14:44   venv/setuptools/command/__pycache__/bdist_rpm.cpython-310.pyc
     6959  2023-12-01 14:44   venv/setuptools/command/__pycache__/sdist.cpython-310.pyc
     2511  2023-12-01 14:44   venv/setuptools/command/__pycache__/rotate.cpython-310.pyc
     2407  2023-12-01 14:44   venv/setuptools/extern/__init__.py
     2939  2023-12-01 14:44   venv/setuptools/extern/__pycache__/__init__.cpython-310.pyc
---------                     -------
20274163                     1538 files


```

--------------------------------

### Simple `actions.yaml` Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/actions-yaml-file

A basic example defining three actions: `pause`, `resume`, and `snapshot`. The `snapshot` action includes a single string parameter for the output filename.

```yaml
pause:
  description: Pause the database.
  additionalProperties: false
resume:
  description: Resume a paused database.
  additionalProperties: false
snapshot:
  description: |
    Take a snapshot of the database.
    Descriptions can be extended to multiple lines.
  params:
    outfile:
      type: string
      description: The filename to write to.
  additionalProperties: false

```

--------------------------------

### Example build-for with all architectures

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/platforms

Use `[all]` to denote an architecture-independent charm that can run anywhere.

```yaml
build-for: [all]

```

--------------------------------

### Full `charmcraft.yaml` Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

This snippet provides a comprehensive example of a `charmcraft.yaml` file, demonstrating the usage of most available keywords for defining a charm's properties, actions, configuration, dependencies, and more.

```yaml
actions:
  snapshot:
    description: Take a snapshot of the database.
    params:
      filename:
        type: string
        description: The name of the snapshot file.
      compression:
        type: object
        description: The type of compression to use.
        properties:
          kind:
            type: string
            enum:
            - gzip
            - bzip2
            - xz
          quality:
            description: Compression quality
            type: integer
            minimum: 0
            maximum: 9
    required:
    - my-favourite-photo.tiff
    additionalProperties: false
analysis:
  ignore:
    attributes:
    - framework
    linters:
    - entrypoint
assumes:
  - any-of:
    - juju >= 2.9.23
    - all-of:
      - juju >= 3.5
      - juju < 4.0
  - k8s-api
base: ubuntu@24.04
build-base: ubuntu@devel
charm-libs:
  - lib: postgresql.postgres_client
    version: "1"
  - lib: mysql.mysql
    version: "0.5"
charm-user: sudoer
config:
  options:
    name:
      default: Wiki
      description: The name, or Title of the Wiki
      type: string
    logo:
      description: URL to fetch logo from
      type: string
    admins:
      description: 'Comma-separated list of admin users to create: user:pass[,user:pass]+'
      type: string
    debug:
      default: false
      type: boolean
      description: turn on debugging features of mediawiki
    port:
      default: 80
      type: int
      description: port on which to serve the wiki
    timeout:
      default: 60.0
      type: float
      description: maximum time before rendering a page will fail
    certificate:
      type: secret
      description: TLS certificate to use for securing connections
containers:
  super-app:
    resource: super-app-image
    mounts:
    - storage: logs
      location: /logs
description: |
  This is a long description of the charm. It gets used when the charm is uploaded to
  Charmhub. It is a string, but can easily be made a multiline string or any other
  YAML string format.
devices:
  super-cool-gpu:
    type: amd.com/gpu
    description: Some sweet AMD GPU
    countmin: 69
    countmax: 420
  lame-gpu:
    type: nvidia.com/gpu
    description: A GPU I regret buying
    countmin: 0
    countmax: 1
extra-bindings:
  Ring of Power: []
links:
  contact: Please send your answer to Old Pink, care of the Funny Farm, Chalfont
  documentation: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file/
  issues:
  - https://launchpad.net/~charmcraft-team
  - https://github.com/canonical/charmcraft/issues
  source:
  - https://github.com/canonical/charmcraft
  website:
  - https://snapcraft.io/charmcraft
name: full-charm
parts:
  my-charm:
    plugin: charm
    source: .
    charm-entrypoint: src/charm.py
    charm-binary-python-packages: []
    charm-python-packages: []
    charm-requirements: [requirements.txt]
    charm-strict-dependencies: false
  another-part:
    plugin: nil
    source: ""
peers:
  friend:
    interface: life
    limit: 150
    optional: true
    scope: container
platforms:
  all:
    build-on:
      - amd64
      - arm64
      - riscv64
      - s390x
      - ppc64el
      - armhf
    build-for: [all]
  amd64:
    build-on: [amd64]
    build-for: [amd64]
  arm64:
    build-on:
      - amd64
      - arm64
    build-for:
      - arm64
provides:
  self:
    interface: identity
requires:
  parent:
    interface: birth
    limit: 2
    optional: false
    scope: global
resources:
  water:
    type: file
    filename: /dev/h2o
  super-app-image:
    type: oci-image
    description: OCI image for the Super App (hub.docker.com/_/super-app)
storage:
  jbod:
    type: block
    description: A nice block storage for me to use as swap space
    properties:
    - transient
subordinate: false
summary: A fully-defined charm, making use of all the available charm keywords.
terms:
 - Butterscotch is regal
 - Cara is adorable
title: My awesome charm
type: charm

```

--------------------------------

### Example Charm Build and Run Environments

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

Illustrates the `bases` key with multiple build and run configurations for different Ubuntu channels and architectures.

```yaml
bases:
  - build-on:
      - name: ubuntu
        channel: '22.04'
        architectures:
          - amd64
          - riscv64
      - name: ubuntu
        channel: '20.04'
        architectures:
          - amd64
          - arm64
    run-on:
      - name: ubuntu
        channel: '22.04'
        architectures:
          - amd64
      - name: ubuntu
        channel: '22.04'
        architectures:
          - riscv64
      - name: ubuntu
        channel: '22.04'
        architectures:
          - arm64
  - build-on:
      - name: ubuntu
        channel: '24.04'
    run-on:
      - name: ubuntu
        channel: '24.04'
        architectures:
          - amd64
          - arm64
          - riscv64
          - s390x
          - ppc64el
          - armhf
```

--------------------------------

### Example Charm Options Configuration

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/config-yaml-file

Provides a concrete example of defining various configuration options for a charm, including strings, booleans, and options with null defaults.

```yaml
options:
  name:
    default: Wiki
    description: The name, or Title of the Wiki
    type: string
  skin:
    default: vector
    description: skin for the Wiki
    type: string
  logo:
    default:
    description: URL to fetch logo from
    type: string
  admins:
    default: Comma-separated list of admin users to create: user:pass[,user:pass]+
    description: turn on debugging features of mediawiki
    type: string
  debug:
    default: false
    type: boolean
    description: turn on debugging features of mediawiki
```

--------------------------------

### Kubernetes Charm `metadata.yaml` Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/metadata-yaml-file

This example demonstrates a comprehensive `metadata.yaml` for a Kubernetes charm, including fields for maintainers, sources, website, containers, resources, and more.

```yaml
name: super-k8s
summary: a really great charm
description: |
  This is a really great charm, whose metadata is suitably complete so as to
  demonstrate as many of the fields as possible.
maintainers:
  - Joe Bloggs <joe.bloggs@email.com>
docs: https://discourse.charmhub.io/t/9999

# The following three fields can be a single string, or a list of strings.
source: https://github.com/foo/super-k8s-operator
issues: https://github.com/foo/super-k8s-operator/issues/
website:
  - https://charmed-super.io/k8s
  - https://super-app.io

containers:
  super-app:
    resource: super-app-image
    mounts:
      - storage: logs
        location: /logs

  super-app-helper:
      bases:
        - name: ubuntu
          channel: ubuntu/24.04
          architectures:
            - amd64
            - arm64

resources:
  super-app-image:
    type: oci-image
    description: OCI image for the Super App (hub.docker.com/_/super-app)

  definitions:
    type: file
    description: A small SQLite3 database of definitions needed by super app
    filename: definitions.db

provides:
  super-worker:
    interface: super-worker

requires:
  ingress:
    interface: ingress
    optional: true
    limit: 1

peers:
  super-replicas:
    interface: super-replicas

storage:
  logs:
    type: filesystem
    location: /logs
    description: Storage mount for application logs

assumes:
  - juju >= 3.6.0
  - k8s-api

charm-user: non-root

```

--------------------------------

### Example build-on with base and architecture

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/platforms

Specify the environments where the platform can build using both base and architecture.

```yaml
build-on:
  - ubuntu@24.04:riscv64

```

--------------------------------

### Install tox and tox-uv with uv

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/tox-ini-file

Install tox and the tox-uv plugin using the uv tool. This is required for Kubernetes and machine profiles.

```bash
uv tool install tox --with tox-uv

```

--------------------------------

### Example LXD Profile Configuration

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/lxd-profile-yaml-file

This example shows the structure of LXD profile configuration as displayed by Juju commands like `juju show-machine` or `juju status --format=yaml`. It includes kernel modules that will be loaded.

```yaml
lxd-profiles:
  juju-default-lxd-profile-0:
    config:
      linux.kernel_modules: openvswitch,ip_tables,ip6_tables

```

--------------------------------

### Install Charmcraft on Linux

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Use this command to install Charmcraft from the stable channel. Ensure you have snapd installed and configured.

```bash
sudo snap install charmcraft --classic
```

--------------------------------

### Example Action Result Output

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-web-app-charms/configure-web-app-charm

This is an example of the output received when the 'updatelogfile' action is successfully executed. It shows the application response and confirmation of the data written to the log file.

```text
Running operation 1 with 1 task
  - task 2 on unit-flask-app-0

Waiting for task 2...
result: |-
  App response: Hello, world!
  Output written to file: Hello, world!


```

--------------------------------

### Initialize Go Module

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

Installs the Go compiler and initializes a new Go module for the project. This sets up the Go development environment.

```bash
sudo snap install go --classic
go mod init go-hello-world

```

--------------------------------

### Example Root Endpoint Response

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Example output from a request to the root endpoint, showing the greeting message.

```json
{"message":"Hi!"}
```

--------------------------------

### Example build-on with different base and architecture

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/platforms

Specify the environments where the platform can build using a different base and architecture combination.

```yaml
build-on:
  - ubuntu@22.04:amd64

```

--------------------------------

### Install Devpack for Spring Boot and Java

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-spring-boot

Installs the devpack-for-spring snap and OpenJDK 21. These are prerequisites for creating the Spring Boot application.

```bash
sudo snap install devpack-for-spring --classic
sudo apt update && sudo apt install -y openjdk-21-jdk

```

--------------------------------

### Install Rockcraft

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Installs Rockcraft using snap with classic confinement. Rockcraft is used for building OCI images (rocks) for charms.

```bash
sudo snap install rockcraft --classic

```

--------------------------------

### Example OCI Image Resource in metadata.yaml

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/metadata-yaml-file

An example of how to define an OCI image resource for a charm, including its type and description.

```yaml
resources:
  super-app-image:
    type: oci-image
    description: OCI image for the Super App (hub.docker.com/_/super-app)
```

--------------------------------

### Install Charmcraft

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Installs Charmcraft using snap with the latest stable channel and classic confinement. Charmcraft is used for building and packaging charms.

```bash
sudo snap install charmcraft --channel latest/stable --classic

```

--------------------------------

### Install Charmcraft (Edge)

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Installs the edge release of Charmcraft with classic confinement. Classic confinement is necessary for Charmcraft's operations.

```bash
sudo snap install charmcraft --channel latest/edge --classic

```

--------------------------------

### Example Charmhub Libraries Declaration

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

Demonstrates how to declare the 'postgresql.postgres_client' and 'mysql.mysql' libraries with their respective versions.

```yaml
charm-libs:
  - lib: postgresql.postgres_client
    version: "1"
  - lib: mysql.mysql
    version: "0.5"
```

--------------------------------

### Example build-on with only architectures

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/platforms

Specify the environments where the platform can build using only architecture names.

```yaml
build-on:
  - amd64
  - riscv64

```

--------------------------------

### Install LXD for Charmcraft

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

These commands install LXD, add the current user to the lxd group, and initialize LXD automatically. This is required for Charmcraft to build charms in containers on Linux.

```bash
sudo snap install lxd
sudo adduser $USER lxd
newgrp lxd
lxd init --auto
```

--------------------------------

### Example: Greeting Response

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

This is the expected output when accessing the root endpoint of the Go application after a request.

```text
Hi!


```

--------------------------------

### Example Charmcraft.yaml with Flask Extension

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-extensions

This is an example of a `charmcraft.yaml` file that includes the 'flask-framework' experimental extension. It defines the charm's name, summary, description, parts, actions, assumptions, containers, provides, requires, resources, and configuration options.

```yaml
name: my-flask-app-k8s
summary: A very short one-line summary of the flask application.
description: |
  A comprehensive overview of your Flask application.
parts:
  charm:
    source: .
    charm-entrypoint: src/charm.py
    charm-binary-python-packages: []
    charm-python-packages: []
    charm-requirements:
    - requirements.txt
    charm-strict-dependencies: false
    plugin: charm
type: charm
bases:
- build-on:
  - name: ubuntu
    channel: '22.04'
  run-on:
  - name: ubuntu
    channel: '22.04'
actions:
  rotate-secret-key:
    description: Rotate the flask secret key. Users will be forced to log in again.
      This might be useful if a security breach occurs.
assumes:
- k8s-api
containers:
  flask-app:
    resource: flask-app-image
peers:
  secret-storage:
    interface: secret-storage
provides:
  metrics-endpoint:
    interface: prometheus_scrape
  grafana-dashboard:
    interface: grafana_dashboard
requires:
  logging:
    interface: loki_push_api
  ingress:
    interface: ingress
    limit: 1
resources:
  flask-app-image:
    type: oci-image
    description: flask application image.
config:
  options:
    webserver-keepalive:
      type: int
      description: Time in seconds for webserver to wait for requests on a Keep-Alive
        connection.
    webserver-threads:
      type: int
      description: Run each webserver worker with the specified number of threads.
    webserver-timeout:
      type: int
      description: Time in seconds to kill and restart silent webserver workers.
    webserver-workers:
      type: int
      description: The number of webserver worker processes for handling requests.
    flask-application-root:
      type: string
      description: Path in which the application / web server is mounted. This configuration
        will set the FLASK_APPLICATION_ROOT environment variable. Run app.config.from_prefixed_env()
        in your Flask application in order to receive this configuration.
    flask-debug:
      type: boolean
      description: Whether Flask debug mode is enabled.
    flask-env:
      type: string
      description: What environment the Flask app is running in, by default it's 'production'.
    flask-permanent-session-lifetime:
      type: int
      description: Time in seconds for the cookie to expire in the Flask application
        permanent sessions. This configuration will set the FLASK_PERMANENT_SESSION_LIFETIME
        environment variable. Run app.config.from_prefixed_env() in your Flask application
        in order to receive this configuration.
    flask-preferred-url-scheme:
      type: string
      default: HTTPS
      description: Scheme for generating external URLs when not in a request context
        in the Flask application. By default, it's "HTTPS". This configuration will
        set the FLASK_PREFERRED_URL_SCHEME environment variable. Run app.config.from_prefixed_env()
        in your Flask application in order to receive this configuration.
    flask-secret-key:
      type: string
      description: The secret key used for securely signing the session cookie and
        for any other security related needs by your Flask application. This configuration
        will set the FLASK_SECRET_KEY environment variable. Run app.config.from_prefixed_env()
        in your Flask application in order to receive this configuration.
    flask-session-cookie-secure:
      type: boolean
      description: Set the secure attribute in the Flask application cookies. This
        configuration will set the FLASK_SESSION_COOKIE_SECURE environment variable.
        Run app.config.from_prefixed_env() in your Flask application in order to
        receive this configuration.

```

--------------------------------

### Minimal `metadata.yaml` Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/metadata-yaml-file

This snippet shows the minimum required fields for a `metadata.yaml` file: name, summary, and description.

```yaml
name: mongodb
summary: A document database
description: A database that stores JSON-like data.

```

--------------------------------

### charmcraft.yaml Configuration Snippet

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Example configuration for `charmcraft.yaml`, defining the name, type, base environment, and supported platforms for the charm.

```yaml
# This file configures Charmcraft.
# See https://juju.is/docs/sdk/charmcraft-config for guidance.

name: fastapi-hello-world

type: charm

base: ubuntu@24.04

# the platforms this charm should be built on and run on.
# you can check your architecture with `dpkg --print-architecture`
platforms:
  amd64:
  # arm64:
  # ppc64el:
  # s390x:


```

--------------------------------

### Build for multiple specific architectures (shorthand)

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/build-guides/select-platforms

The shorthand notation can be used when `build-on` and `build-for` entries are identical for each platform. This achieves the same result as the previous example.

```yaml
base: ubuntu@24.04
platforms:
  amd64:
  riscv64:

```

--------------------------------

### Check Charmcraft Version

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Run this command to verify the installed version of Charmcraft.

```bash
charmcraft version

```

--------------------------------

### Example Charm User Privilege

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

Sets the charm to run with sudoer privileges, allowing it to elevate its permissions when necessary.

```yaml
charm-user: sudoer
```

--------------------------------

### Clone a legacy hooks-based charm

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/build-guides/pack-a-hooks-based-charm-with-charmcraft

Clone the example tiny-bash charm from GitHub to start the process.

```bash
git clone https://github.com/erik78se/tiny-bash

```

--------------------------------

### Create Project Directory

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Creates and enters a new directory for the tutorial project. This organizes project files.

```bash
mkdir django-tutorial
cd django-tutorial

```

--------------------------------

### List libraries for a charm

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/commands/list-lib

This example shows how to list all libraries published by a specific charm on Charmhub. It displays the library name and its API and patch versions.

```bash
charmcraft list-lib my-charm
```

--------------------------------

### Build for multiple specific architectures

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/build-guides/select-platforms

Declare multiple architectures in the `platforms` key to build separate artifacts for each. This example builds for both AMD64 and RISC-V.

```yaml
base: ubuntu@24.04
platforms:
  amd64:
    build-on: [amd64]
    build-for: [amd64]
  riscv64:
    build-on: [riscv64]
    build-for: [riscv64]

```

--------------------------------

### Run Django Development Server

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Starts the Django development server, listening on all interfaces on port 8000. This allows testing the app locally.

```bash
./manage.py runserver 0.0.0.0:8000

```

--------------------------------

### Select build and target architecture for a charm

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/build-guides/select-platforms

Specify the architecture for building and running your charm. This example targets AMD64 architecture on Ubuntu 24.04 LTS.

```yaml
base: ubuntu@24.04
platforms:
  amd64:
    build-on: [amd64]
    build-for: [amd64]

```

--------------------------------

### Example charm initialization session

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charms

Demonstrates a typical session for initializing a Flask framework charm for Kubernetes. It includes creating a directory, navigating into it, and running the `charmcraft init` command with the `flask-framework` profile. The output shows the initialized files and directory structure.

```bash
mkdir my-flask-app-k8s
cd my-flask-app-k8s/
charmcraft init --profile flask-framework
```

```text
Charmed operator package file and directory tree initialised
Now edit the following package files to provide fundamental charm metadata
and other information:

charmcraft.yaml
src/charm.py
README.md

```

```bash
ls -R
```

```text
.:
charmcraft.yaml  requirements.txt  src

./src:
charm.py

```

--------------------------------

### Start Express App

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Starts the Express.js application. The app will typically be accessible on localhost:3000.

```bash
npm start

```

--------------------------------

### Uninstall Charmcraft (Snap Installation)

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Use this command to remove Charmcraft if it was installed on Linux via snap.

```bash
sudo snap remove charmcraft

```

--------------------------------

### Initialize a charm project with a profile

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charms

Use `charmcraft init` with the `--profile` flag to create a new charm project. Specify a profile like `machine`, `kubernetes`, or a framework-specific one (e.g., `flask-framework`). This command sets up the necessary directory structure and initial files.

```bash
charmcraft init --profile <profile>
```

--------------------------------

### Example Visitors Endpoint Response

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Example output from a request to the /visitors endpoint, showing an incremented visitor count.

```json
{"count":2}
```

--------------------------------

### Example of Upstream Source Key in metadata.yaml

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/metadata-yaml-file

An example of an 'upstream-source' key, which is ignored by Juju but can be used for tracking purposes.

```yaml
# The upstream-source field is ignored by Juju. It is included here as a reference
```

--------------------------------

### Initialize a Library with Charmcraft

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-libraries

Run this command in your charm's root directory to create a template file for a new library. Ensure you have registered ownership of your charm's name on Charmhub before proceeding.

```bash
charmcraft create-lib <lib-name>
```

--------------------------------

### Assumes Block: Simple Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/metadata-yaml-file

A basic example of the 'assumes' block, specifying Juju version and Kubernetes API requirements.

```yaml
assumes:
  - juju >= 2.9.23
  - k8s-api
```

--------------------------------

### Initialize a new charm project

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/commands/init

Use this command to create a new charm project. It sets up a standard directory structure and essential configuration files. You can specify a profile to tailor the project setup for different deployment environments or frameworks.

```bash
charmcraft init
```

```bash
charmcraft init --profile kubernetes
```

```bash
charmcraft init --profile machine
```

```bash
charmcraft init --profile django-framework
```

```bash
charmcraft init --profile fastapi-framework
```

```bash
charmcraft init --profile flask-framework
```

```bash
charmcraft init --profile go-framework
```

```bash
charmcraft init --profile spring-boot-framework
```

--------------------------------

### Install Python Dependencies

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Installs the Python packages listed in the requirements.txt file using pip within the activated virtual environment.

```bash
pip install -r requirements.txt

```

--------------------------------

### Create Django Project

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Initializes a new Django project named `django_hello_world` using the `django-admin` command.

```bash
django-admin startproject django_hello_world

```

--------------------------------

### Install pg-promise Package

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Installs the pg-promise package, a popular PostgreSQL framework for Node.js, which is often used for database interactions in Express applications.

```bash
npm install pg-promise

```

--------------------------------

### Install and Bootstrap Juju

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Installs Juju and bootstraps a development controller using MicroK8s. Juju is used for deploying and managing applications on Kubernetes.

```bash
sudo snap install juju --channel 3.6/stable
mkdir -p ~/.local/share
juju bootstrap microk8s dev-controller

```

--------------------------------

### Initialize Charmcraft Project

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

Initializes a new Charmcraft project with a Go framework profile, automating the creation of necessary charm files including charmcraft.yaml.

```bash
charmcraft init --profile go-framework --name go-hello-world

```

--------------------------------

### Initialize Alembic Migration Environment

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-web-app-charms/use-a-database

Run this command in your project root to set up the Alembic migration environment.

```bash
alembic init alembic

```

--------------------------------

### Install Charmcraft using Homebrew on macOS

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Use this command to install Charmcraft if you are using Homebrew on macOS. Ensure Homebrew is already set up.

```bash
brew install charmcraft

```

--------------------------------

### Install Express App Dependencies

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Installs the Node.js dependencies required for the Express application to run. This command should be executed within the application's directory.

```bash
npm install

```

--------------------------------

### Go Hello World Application

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

A simple Go HTTP server that responds with 'Hello, world!' to requests on the root path. It logs incoming requests and when it starts.

```go
package main

import (
  "fmt"
  "log"
  "net/http"
)

func helloWorldHandler(w http.ResponseWriter, req *http.Request) {
  log.Printf("new hello world request")
  fmt.Fprintln(w, "Hello, world!")
}

func main() {
  log.Printf("starting hello world application")
  http.HandleFunc("/", helloWorldHandler)
  http.ListenAndServe(":8080", nil)
}

```

--------------------------------

### Select build and target architecture using shorthand

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/build-guides/select-platforms

Use the shorthand notation when the build-on and build-for architectures are identical. This example targets AMD64 architecture on Ubuntu 24.04 LTS.

```yaml
base: ubuntu@24.04
platforms:
  amd64:

```

--------------------------------

### Install npm and Express Generator

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Installs Node Package Manager (npm) and the express-generator tool globally. These are needed to scaffold a new Express.js application.

```bash
sudo apt update -y && sudo apt install npm -y
sudo npm install -g express-generator@4

```

--------------------------------

### Initialize Rockcraft Project

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

Initializes a new Rockcraft project with a Go framework profile. This automates the creation of the rockcraft.yaml file.

```bash
rockcraft init --profile go-framework

```

--------------------------------

### Install Rockcraft (Edge)

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-fastapi

Installs the edge release of Rockcraft with classic confinement. Classic confinement is required for Rockcraft to access the entire file system.

```bash
sudo snap install rockcraft --channel latest/edge --classic

```

--------------------------------

### Install Charmcraft in a Multipass VM

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-charmcraft

Access the Multipass VM shell and install Charmcraft using snap. This ensures an isolated and consistent development environment.

```bash
multipass shell charm-dev
... 
ubuntu@charm-dev:~$ sudo snap install charmcraft --classic
charmcraft 2.2.0 from Canonical✓ installed

```

--------------------------------

### Pack and Upload Rockcraft Image

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Use rockcraft to pack the application and skopeo to copy the image to a local registry.

```bash
rockcraft pack
rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:flask-hello-world_0.2_$(dpkg --print-architecture).rock \
  docker://localhost:32000/flask-hello-world:0.2

```

--------------------------------

### Pack and upload the rock

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Use `rockcraft pack` to create the rock archive and `rockcraft.skopeo` to copy it to a local registry.

```bash
rockcraft pack
rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:expressjs-hello-world_0.3_$(dpkg --print-architecture).rock \
  docker://localhost:32000/expressjs-hello-world:0.3

```

--------------------------------

### Install MicroK8s

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Installs MicroK8s, a lightweight Kubernetes distribution, using a specific channel. It also adds the current user to the snap_microk8s group and activates the changes.

```bash
sudo snap install microk8s --channel 1.31-strict/stable
sudo adduser $USER snap_microk8s
newgrp snap_microk8s

```

--------------------------------

### Initialize a charm project with custom options

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/commands/init

Customize the charm initialization process by specifying the author, charm name, project directory, and whether to force the initialization in a non-empty directory. The `--force` option will not overwrite existing files.

```bash
charmcraft init --author "My Name" --name "my-charm" --project-dir ./my-charm-dir
```

```bash
charmcraft init -f
```

--------------------------------

### Express.js Application Setup

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-express

Standard Express.js application setup including static file serving, routing, and error handling. This forms the boilerplate for a typical web application.

```javascript
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/visitors', visitorsRouter);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

module.exports = app;
```

--------------------------------

### Build Go Application

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

Compiles the Go source code into an executable binary. This prepares the application for local execution.

```bash
go build .

```

--------------------------------

### Initialize Go 12-factor app charm

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-web-app-charms

Use this command to initialize a 12-factor app charm for a Go framework. It automatically creates necessary project files.

```bash
charmcraft init --profile go-framework

```

--------------------------------

### Pack and upload the rock

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Use `rockcraft pack` to package the charm and `rockcraft.skopeo` to copy the OCI archive to a registry. This prepares the charm for deployment.

```bash
rockcraft pack
rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:django-hello-world_0.2_$(dpkg --print-architecture).rock \
  docker://localhost:32000/django-hello-world:0.2

```

--------------------------------

### Initialize LXD

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Initializes LXD with default settings. This is necessary before using LXD for building.

```bash
lxd init --auto

```

--------------------------------

### List all available extensions

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-extensions

Run this command to see all extensions supported by Rockcraft or Charmcraft. It displays the extension name and supported bases.

```bash
$ charmcraft list-extensions
Extension name    Supported bases    Experimental bases
----------------  -----------------  --------------------
flask-framework                      ubuntu@22.04

```

--------------------------------

### Check LXD Version

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-flask

Checks if LXD is installed. LXD is required for building the rock.

```bash
lxd --version

```

--------------------------------

### Create Charm Directory

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-spring-boot

Creates a new directory for the charm and navigates into it. This is the first step in setting up your charm project.

```bash
mkdir charm
cd charm
```

--------------------------------

### Charmcraft YAML Configuration Example

Source: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file

This snippet illustrates a comprehensive charmcraft.yaml configuration, including settings for analysis, assumptions, base images, charm libraries, user, configuration options, containers, description, devices, extra bindings, and links.

```yaml
analysis:
  ignore:
    attributes:
    - framework
    linters:
    - entrypoint
assumes:
  - any-of:
    - juju >= 2.9.23
    - all-of:
      - juju >= 3.5
      - juju < 4.0
  - k8s-api
base: ubuntu@24.04
build-base: ubuntu@devel
charm-libs:
  - lib: postgresql.postgres_client
    version: "1"
  - lib: mysql.mysql
    version: "0.5"
charm-user: sudoer
config:
  options:
    name:
      default: Wiki
      description: The name, or Title of the Wiki
      type: string
    logo:
      description: URL to fetch logo from
      type: string
    admins:
      description: 'Comma-separated list of admin users to create: user:pass[,user:pass]+'
      type: string
    debug:
      default: false
      type: boolean
      description: turn on debugging features of mediawiki
    port:
      default: 80
      type: int
      description: port on which to serve the wiki
    timeout:
      default: 60.0
      type: float
      description: maximum time before rendering a page will fail
    certificate:
      type: secret
      description: TLS certificate to use for securing connections
containers:
  super-app:
    resource: super-app-image
    mounts:
    - storage: logs
      location: /logs
description: |
  This is a long description of the charm. It gets used when the charm is uploaded to
  Charmhub. It is a string, but can easily be made a multiline string or any other
  YAML string format.
devices:
  super-cool-gpu:
    type: amd.com/gpu
    description: Some sweet AMD GPU
    countmin: 69
    countmax: 420
  lame-gpu:
    type: nvidia.com/gpu
    description: A GPU I regret buying
    countmin: 0
    countmax: 1
extra-bindings:
  Ring of Power: 
links:
  contact: Please send your answer to Old Pink, care of the Funny Farm, Chalfont
  documentation: https://documentation.ubuntu.com/charmcraft/stable/reference/files/charmcraft-yaml-file/
  issues:
  - https://launchpad.net/~charmcraft-team
  - https://github.com/canonical/charmcraft/issues
  source:
  - https://github.com/canonical/charmcraft
  website:
  - https://snapcraft.io/charmcraft
name: full-charm
```

--------------------------------

### Pack and upload the rock to a local container registry

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-web-app-charms/use-a-database

Use `rockcraft pack` to create a rock archive and `rockcraft.skopeo copy` to upload it to a local container registry.

```bash
rockcraft pack
```

```bash
rockcraft.skopeo copy \
--insecure-policy \
--dest-tls-verify=false \
oci-archive:fastapi-hello-world_0.2_$(dpkg --print-architecture).rock 
docker://localhost:32000/fastapi-hello-world:0.2
```

--------------------------------

### Get application IP address

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-web-app-charms/use-a-database

Retrieve the IP address of the deployed application using `juju status`.

```bash
juju status
```

--------------------------------

### Initialize a charm with a specific extension

Source: https://documentation.ubuntu.com/charmcraft/stable/howto/manage-extensions

Use this command to initialize a new charm project with a pre-defined profile that includes a specific extension, such as 'flask-framework'. This sets up the basic project structure and configuration.

```bash
mkdir my-flask-app-k8s
cd my-flask-app-k8s/
charmcraft init --profile flask-framework

```

```text
Charmed operator package file and directory tree initialised.

Now edit the following package files to provide fundamental charm metadata
and other information:

charmcraft.yaml
src/charm.py
README.md

```

```bash
ls -R

```

```text
.:
charmcraft.yaml  requirements.txt  src

./src:
charm.py

```

```bash
cat charmcraft.yaml

```

```yaml
name: my-flask-app-k8s

type: charm

bases:
  - build-on:
    - name: ubuntu
      channel: "22.04"
    run-on:
    - name: ubuntu
      channel: "22.04"

# (Required)
summary: A very short one-line summary of the flask application.

# (Required)
description: |
  A comprehensive overview of your Flask application.

extensions:
  - flask-framework

# Uncomment the integrations used by your application
# requires:
#   mysql: 

```

--------------------------------

### Run Go Application Locally

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-go

Executes the compiled Go application. The application will start listening on port 8080.

```bash
./go-hello-world

```

--------------------------------

### Initialize Rockcraft project for Django

Source: https://documentation.ubuntu.com/charmcraft/stable/tutorial/kubernetes-charm-django

Use `rockcraft init` with the `--profile django-framework` to automatically generate a `rockcraft.yaml` file tailored for Django applications.

```bash
cd ..
rockcraft init --name django-hello-world --profile django-framework
```
Tokens:
Raw