Go framework extension

The go-framework extension includes configuration options customised for a Go application. This document describes all the keys that a user may interact with.

Tip

If you’d like to see the full contents contributed by this extension, see How to manage extensions.

charmcraft.yaml > config > options

You can use the predefined options (run charmcraft expand-extensions for details) but also add your own, as needed.

The predefined configuration options for the go-framework are: - app-port: Port in which the application should listen. The ingress will be configured using this port. The environment variable passed to the app is APP_PORT. Default value is 8080. - app-secret-key: Long secret you can use for sessions, csrf or any other thing where you need a random secret shared by all units. The environment variable passed to the app is APP_METRICS_PORT. The default value is random. - metrics-port: Port where the prometheus metrics will be scraped. The environment variable passed to the app is APP_PORT. Default value is 8080. - metrics-path: Path where the prometheus metrics will be scraped. The environment variable passed to the app is APP_METRICS_PATH. Default value is /metrics.

In case you want to add extra configuration options, any option you define will be used to generate environment variables; a user-defined option config-option-name will generate an environment variable named APP_CONFIG_OPTION_NAME where the option name is converted to upper case and dashes are converted to underscores.

In either case, you will be able to set it in the usual way by running juju config <application> <option>=<value>. For example, if you define an option called token, as below, this will generate a APP_TOKEN environment variable, and a user of your charm can set it by running juju config <application> token=<token>.

config:
  options:
    token:
      description: The token for the service.
      type: string

In addition to this, you can set the configuration option to be mandatory by setting the optional key to false. This will block the charm and stop services until the configuration is supplied. For example, if your application needs an api-token to function correctly you can set optional, as shown below. This will block the charm and stop the services until the api-token configuration is supplied.

charmcraft.yaml

config:
  options:
    api-token:
      description: The token necessary for the service to run.
      type: string
      optional: false

Note

A configuration with optional: false can’t also have a default key. If it has both, the charm will fail to pack.

peers, provides, and requires keys

Your charm already has some peers, provides, and requires integrations, for internal purposes.

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

In addition to these integrations, in each provides and requires block you may specify further integration endpoints, to integrate with the following charms and bundles:

• Ingress: traefik and nginx ingress integrator

• MySQL: machine and k8s charm

• PostgreSQL: machine and k8s charm

• MongoDB

• Canonical Observability Stack (COS)

• Redis

• SAML

• S3

• RabbitMQ: machine and k8s charm

• Tempo

• SMTP

These endpoint definitions are as below:

requires:
  mysql:
    interface: mysql_client
    optional: True
    limit: 1

requires:
  postgresql:
    interface: postgresql_client
    optional: True
    limit: 1

requires:
  mongodb:
    interface: mongodb_client
    optional: True
    limit: 1

requires:
  redis:
    interface: redis
    optional: True
    limit: 1

requires:
  saml:
    interface: saml
    optional: True
    limit: 1

requires:
  s3:
    interface: s3
    optional: True
    limit: 1

requires:
  rabbitmq:
    interface: rabbitmq
    optional: True
    limit: 1

requires:
  tracing:
    interface: tracing
    optional: True
    limit: 1

requires:
  smtp:
    interface: smtp
    optional: True
    limit: 1

Note

The key optional with value False means that the charm will get blocked and stop the services if the integration is not provided.

To add one of these integrations, e.g., PostgreSQL, in the project file, include the appropriate requires block and integrate with juju integrate <go charm> postgresql as usual.

After the integration has been established, the connection string will be available as an environment variable. Integration with PostgreSQL, MySQL, MongoDB or Redis provides the string as the POSTGRESQL_DB_CONNECT_STRING, MYSQL_DB_CONNECT_STRING, MONGODB_DB_CONNECT_STRING or REDIS_DB_CONNECT_STRING environment variables respectively. Furthermore, the following environment variables will be provided to your Go application for integrations with PostgreSQL, MySQL, MongoDB or Redis:

• <integration>_DB_SCHEME

• <integration>_DB_NETLOC

• <integration>_DB_PATH

• <integration>_DB_PARAMS

• <integration>_DB_QUERY

• <integration>_DB_FRAGMENT

• <integration>_DB_USERNAME

• <integration>_DB_PASSWORD

• <integration>_DB_HOSTNAME

• <integration>_DB_PORT

• <integration>_DB_NAME

Here, <integration> is replaced by POSTGRESQL, MYSQL MONGODB or REDIS for the relevant integration.

The provided SAML environment variables are as follows:

• SAML_ENTITY_ID (required)

• SAML_METADATA_URL (required)

• SAML_SINGLE_SIGN_ON_REDIRECT_URL (required)

• SAML_SIGNING_CERTIFICATE (required)

The S3 integration creates the following environment variables that you may use to configure your Go application:

• S3_ACCESS_KEY (required)

• S3_SECRET_KEY (required)

• S3_BUCKET (required)

• S3_REGION

• S3_STORAGE_CLASS

• S3_ENDPOINT

• S3_PATH

• S3_API_VERSION

• S3_URI_STYLE

• S3_ADDRESSING_STYLE

• S3_ATTRIBUTES

• S3_TLS_CA_CHAIN

The RabbitMQ integration creates the connection string in the environment variable RABBITMQ_CONNECT_STRING. Furthermore, the following environment variables may be provided, derived from the connection string:

• RABBITMQ_SCHEME

• RABBITMQ_NETLOC

• RABBITMQ_PATH

• RABBITMQ_PARAMS

• RABBITMQ_QUERY

• RABBITMQ_FRAGMENT

• RABBITMQ_USERNAME

• RABBITMQ_PASSWORD

• RABBITMQ_HOSTNAME

• RABBITMQ_PORT

• RABBITMQ_VHOST

The Tracing integration creates the following environment variables that you can use to configure your application:

• OTEL_EXPORTER_OTLP_ENDPOINT

• OTEL_SERVICE_NAME

The provided SMTP environment variables are as follows:

• SMTP_HOST

• SMTP_PORT

• SMTP_USER

• SMTP_PASSWORD_ID

• SMTP_AUTH_TYPE

• SMTP_TRANSPORT_SECURITY

• SMTP_DOMAIN

The environment variable APP_BASE_URL provides the Ingress URL for an Ingress integration or the Kubernetes service URL if there is no Ingress integration.

HTTP Proxy

Proxy settings should be set as model configurations. Charms generated using the go-framework extension will make the Juju proxy settings available as the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables. For example, the juju-http-proxy environment variable will be exposed as HTTP_PROXY to the Go service.

See more: List of model configuration keys

Background Tasks

Extra services defined in the file rockcraft.yaml with names ending in -worker or -scheduler will be passed the same environment variables as the main application. If there is more than one unit in the application, the services with the name ending in -worker will run in all units. The services with name ending in -scheduler will only run in one of the units of the application.

Observability

12-Factor charms are designed to be easily observable using the Canonical Observability Stack.

You can easily integrate your charm with Loki, Prometheus and Grafana using Juju.

juju integrate go-k8s grafana
juju integrate go-k8s loki
juju integrate go-k8s prometheus

After integration, you will be able to observe your workload using Grafana dashboards.

In addition to that you can also trace your workload code using Tempo.

To learn about how to deploy Tempo you can read the documentation here.

OpenTelemetry will automatically read the environment variables and configure the OpenTelemetry SDK to use them. See the OpenTelemetry documentation for further information about tracing.

Secrets

Juju secrets can be passed as environment variables to your Go application. The secret ID has to be passed to the application as a config option in the project file of type secret. This config option has to be populated with the secret ID, in the format secret:<secret ID>.

The environment variable name passed to the application will be:

APP_<config option name>_<key inside the secret>

The <config option name> and <key inside the secret> keywords in the environment variable name will have the hyphens replaced by underscores and all the letters capitalised.

See more: Juju | Secret