how-to

Accessing topics from an application

This guide shows you how to access Kafka topics from your application. You need an existing topic to access. See Create a Kafka topic for how to create a topic.

Add labels to your resources

This guide shows you how to add labels to your resources, either through your manifest or through Nais Console.

Adding logs to your Grafana dashboard

Add logs to your Grafana dashboards and correlate them with metrics and traces.

Additional users

You can add users to your database by setting database configuration option: .spec.gcp.sqlInstances[].databases[].users[].name. Additional users needs to manually be given access to the database and…

Advanced: Secrets with binary data

Nais Console only supports secrets with string values. You can work around this by Base64-encoding the binary data and store the resulting string, though it also requires that your application does…

Alert on vulnerabilities

Set up Prometheus or Grafana alerts for vulnerability findings in your workloads, including critical severity, priority-based findings, and high risk scores.

Audit logs

Most applications where a user processes data related to another user need to log audit statements, detailing which user did what action on which subject. These logs need to follow a specific format…

Avoid false errors from expected 4xx responses

Fix inflated error rates in APM caused by exceptions that produce expected 4xx responses.

Avro and schema

This guide will show you how to do various schema operations on your Kafka topics. To register the first version of a schema under the subject "team.test-key" using Avro schema:

Build and deploy with GitHub Actions

This how-to guide shows you how to build and deploy your application using GitHub Actions and the Nais deploy action.

Certification sync issues

If you have deleted your application and recreate it, there might be an issue that your new app will not be able to create a client certificate because the old one still exists. Your deploy may fail…

Change the tier of your database instance

Choosing an appropriate tier depends on your application's requirements such as: The tier you choose will affect the performance and cost of your database.

Communicate reliably between GCP and on-prem

This guide shows you how to configure HTTP clients to handle firewall timeouts when calling on-premises services from GCP.

Communicate with other workloads

This guide shows you how to communicate with other workloads inside the same environment or cluster via service discovery.

Connect from laptop

In the event of problems that can not be resolved via the application, a developer might need to access the database directly.

Connect to a cloned database

If you have for some reason cloned a database in the console, you need to do some manually changes on the new database to be allowed to connect to it with your.

Consume external API using Maskinporten

This how-to guides you through the steps required to consume an API secured with Maskinporten: Declare all the scopes that you want to consume in your application's Nais manifest so that your…

Consume internal API as an application

This how-to guides you through the steps required to consume an API secured with Entra ID as an application (or a machine user). This is also known as the machine-to-machine (M2M) or client…

Consume internal API on behalf of a citizen

This how-to guides you through the steps required to consume an API secured with TokenX: Enable TokenX in your application:

Consume internal API on behalf of an employee

This how-to guides you through the steps required to consume an API secured with Entra ID on behalf of an employee. This is also known as the on-behalf-of (OBO) flow.

Correlate traces and logs

Learn how to correlate traces with logs in Grafana Tempo.

Create a bucket

This guide will show you how to create a Google Cloud Storage bucket. You create the bucket through the Nais application manifest.

Create a dashboard in Grafana

Create a dashboard in Grafana for your application

Create a Kafka topic

This guide will show you how to create a Kafka topic. The fully qualified topic name is the name of the Topic resource prefixed with your team namespace:

Create a Nais team

This how-to guide shows you how to create a Nais team. Your team will now be created, and you will be the owner.

Create a Valkey instance explicitly (legacy)

We recommend creating your Valkey instances in their own workflow for more control over configuration, especially if you intend for multiple applications using the same Valkey instance, or if you…

Create alert in Grafana

Learn how to create an alert for your application in Grafana.

Create alert with Prometheus

Create alerts for your application using Prometheus.

Create alerts from templates

Turn a Nais APM issue or service into a Grafana alert rule using the built-in error-rate, SLO burn-rate, exception-spike, web-vitals, and new-exception templates.

Create alerts in nav-logs (OpenSearch Dashboards)

This guide will help you create alerts in nav-logs (OpenSearch Dashboards).

Create an instance of BigQuery

Below is a minimal working example for a Nais Application manifest.

Create an OpenSearch instance (legacy)

Explicitly creating an OpenSearch instance is done by adding a OpenSearch resource to your namespace with detailed configuration in a GCP cluster. In your Application or Naisjob specifications, you…

Create and manage configs in Console

This how-to guide shows you how to create and manage a config in the Nais Console. 🎯 Learn how to use a config in your workload

Create and manage secrets in Console

This how-to guide shows you how to create and manage a secret in the Nais Console. 🎯 Learn how to use a secret in your workload

Create application

This how-to guide will show you how to create a Nais manifest for your application. Inside your application repository, create a .nais-folder.

Create job

This how-to guide will show you how to create a Nais manifest for your job. Inside your job repository, create a .nais-folder.

Create OpenSearch

This guide will show you how to create a OpenSearch instance for your team using Nais Console. Creating the OpenSearch instance will take a few minutes. The Status column will show you the current…

Create Valkey

This guide will show you how to create a Valkey instance for your team using Nais Console. Creating the Valkey instance will take a few minutes. The Status column will show you the current state.

Custom frontend metrics

Send custom measurements from the browser and query them in Grafana.

Customize Prometheus alerts

Advanced guide to customized Prometheus alerts

Debugging

When issues arise with your Postgres cluster, you can use the following steps to troubleshoot the problem.

Debugging

When issues arise with your Cloud SQL instance, you can use the following steps to troubleshoot the problem.

Debugging workloads

A useful place to start when you have problems getting your pods running is the troubleshooting guide.

Delete Kafka topic and data

When you want to delete a Kafka topic and it's data, the Topic resource in Nais needs to be annotated.

Delete OpenSearch

This page guides you through the steps required to delete an OpenSearch instance. Ensure that all references to the opensearch instance are removed from your workload manifests:

Delete Valkey

This page guides you through the steps required to delete a Valkey instance. Ensure that all references to the Valkey instance are removed from your workload manifests:

Delete your application

Delete your job

Deleting a bucket

Delete unused buckets to avoid incurring unnecessary costs. A bucket is deleted by enabling cascading deletion, and deleting the application.

Deleting the database

The database is not automatically removed when deleting your Nais application. Remove unused databases to avoid incurring unnecessary costs. This is done by setting cascadingDelete in your…

Deleting the database

This page guides you through the steps required to delete a Postgres cluster. Ensure that all references to the Postgres instance are removed from your workload manifests:

Dependabot with auto-merge

Dependabot is a security tool offered by GitHub. Dependabot scans your repositories for vulnerabilities and outdated dependencies, and may automatically open pull requests to bump dependency…

Disable persistent application logs

Disable log storage for a specific application

Disable read-only file system

This how-to shows how to disable read-only root file system in your workloads. Re-deploy your workload to apply the changes.

Enable audit logging

This guide describes how to enable audit logging in your postgreSQL database. The following steps need to be taken to enable the logging.

Enable Leader Election

This guide will show you how to enable leader election for your application. 👷 Help Wanted! Please contribute with examples on how to use the Server Sent Events API.

Enable session replay

Opt in to masked session replay or crash snapshots in @nais/apm, understand the non-overridable masking floor, and make the privacy decision your team owns.

Expose an application

This guide will show you how to expose your application to end-users or applications in other environments by using an ingress.

Expose FSS apps with KrakenD

KrakenD is an open-source API Gateway that sits in front of your Maskinporten APIs and provides a single point of entry for API clients.

Expose metrics from your application

Expose metrics from your application

Failing to assign private IP to an existing Cloud SQL instance

If you have deleted your application and recreate it, there might be an issue that your new app will not be able to create a client certificate because the old one still exists. Your deploy may fail…

Frontend-to-backend trace propagation

Connect frontend browser traces to backend spans for end-to-end visibility.

Generate a token from Entra ID for development

This how-to guides you through the steps required to generate a token that you can use against an API secured with Entra ID in the development environments.

Generate a token from TokenX for development

This how-to guides you through the steps required to generate a token that you can use against an API secured with TokenX in the development environments.

Generate SBOM

Simply add nais/docker-build-push to your workflow. The nais/docker-build-push action default push to Google Container Registry (GAR). If you want to push to another registry, you can use the…

Get access to the dashboard

Each OpenSearch instance in Aiven comes with a built-in dashboard for visualizing your data. To get access to this dashboard you need to follow these steps:

Get backend exceptions into Issues

Get your backend exceptions — JVM (Spring Boot, Ktor) and Node.js — into the Nais APM Issues tab with tight grouping and a stack trace, whether you log to stdout (the default) or export logs over OpenTelemetry.

Get started with auto-instrumentation

Enable auto-instrumentation to collect traces and runtime metrics from your application without code changes.

Get started with Grafana Loki

Get started with Grafana Loki, the default and preferred log aggregation system for all Nais application

Get started with Grafana Tempo

Grafana Tempo is a distributed tracing backend that stores and queries traces. It is integrated with Grafana, so you can visualize and query traces alongside your metrics and logs.

Get started with nav-logs

This guide will help you get started with nav-logs (OpenSearch Dashboards).

Get started with Team Logs

Get started with Team Logs, a private logging solution leveraging Google Cloud Logs.

Get temporary Kafka credentials

Use the nais-cli to get temporary credentials for Kafka. This is useful for debugging, running kafka-consumer-groups.sh, or connecting from outside Nais.

Get temporary OpenSearch credentials

Use the nais-cli to get temporary credentials for an OpenSearch instance. This is useful for debugging, accessing the dashboard, or connecting from outside Nais.

How to turn on Tiered Storage for your Kafka topic

This guide shows you how to enable tiered storage for your Kafka topic. You need to own an existing topic in nais. Check Create a Kafka topic for how to create a topic.

Install naisdevice

A macOS systray exemplifying a red-colored naisdevice icon. When you have started Naisdevice the Naisdevice icon appears in your Systray (where all your small program icons are located - see above…

Kafka metrics

This guide will show you how to monitor your Kafka topics with Grafana. This is a user-generated list of metrics that can be used with Grafana to monitor your Kafka topics.

Log in a citizen

This how-to guides you through the steps required to ensure that only citizens authenticated with ID-porten can access your application.

Log in an employee

This how-to guides you through the steps required to ensure that only employees authenticated with Entra ID can access your application.

Log in users

This guide shows you how to log in users to your application with the login proxy. Before you begin, ensure that you have:

Make database queries visible

The instrumentation the Nais APM Database tab needs — OpenTelemetry client spans with db.system, and connection-pool metrics for pool health.

Manage access

This guide will show you how to manage access to your topic. See https://nais.io/log/#2026-01-29-nais-cli-kafka-acls.

Manage CDN assets

This how-to guide shows you how to list and manage assets on the CDN. In most cases you only need to upload new assets through the GitHub Action. In the rare case you need to manage the assets…

Metrics and alerts for logs

Use Loki-derived metrics to monitor log patterns and create Prometheus alerts.

Migrate from Sentry to @nais/apm

Move a frontend app off @sentry/* and onto the @nais/apm SDK — a clean, full migration with a concept map, a copy-pasteable recipe, and an honest list of what is different and what is not supported yet.

Migrate OpenSearch management to Nais Console

This guide will help you migrate an existing OpenSearch instance to instead be managed via Nais Console.

Migrate to new instance

This guide describes how to migrate your PostgreSQL database to a new SQLInstance. The process can be summarized as follows:

Migrate Valkey management to Nais Console

This guide will help you migrate an existing Valkey instance to instead be managed via Nais Console.

Migrating databases to GCP

Suggested patterns for moving on-prem databases to GCP postgreSQL. Disclaimer: These are options for migrations to GCP postgreSQL. Others may work better for your team.

Migrating to GCP

Our GCP clusters use a zero trust security model, implying that the application must specify both incoming and outgoing connections in order to receive or send traffic at all. This is expressed using…

Next.js quickstart with @nais/apm

Instrument a Next.js app with @nais/apm — client init, an error boundary, route tracking, and opt-in tracing. Covers both the App Router and the Pages Router.

Overriding user and group that runs container process

This how-to shows you how to override the default user and group (1069) that will run your container process.

Personal database access

Databases should always be accessed using a personal account, and the access should ideally be temporary.

Postgres database metrics

All PostgreSQL databases running in the cluster export metrics using the Prometheus postgres exporter.

Postgres database metrics

All Postgres databases running on Google Cloud Platform are integrated with Cloud Monitoring to provide metrics and alerts. You can use these metrics to monitor the health and performance of your…

Push metrics to Prometheus

Push metrics to Prometheus

React + Vite quickstart with @nais/apm

Instrument a React single-page app built with Vite using @nais/apm — init at the entry point, an error boundary, and React Router route tracking.

Redirect a client

To redirect traffic from one domain to another, you need to define an ingress from the old domain that redirects to the new domain, with .spec.redirects[].

Reduce costs

Most teams can cut their GCP costs with a few changes to their nais.yaml manifests. The largest savings come from right-sizing database instances, adjusting resource requests, and tuning replica…

Remove access to topics from an application

This guide will show you how to remove your application's access to a Kafka topic. Remove the ACL that grants your application access to the topic.

Reset database credentials

To reset the database credentials for your application (if application name, database name or envVarPrefix has been changed), you need to first delete the secret and sqluser for the database:

Secure your API with Entra ID

This how-to guides you through the steps required to secure your API using Entra ID: Depending on who your consumers are, you must grant access to either applications, users, or both.

Secure your API with Maskinporten

This how-to guides you through the steps required to secure your API using Maskinporten: A scope represents a permission that a given consumer has access to.

Secure your API with TokenX

This how-to guides you through the steps required to secure your API using TokenX: Specify inbound access policies to authorize your consumers:

Set up access policies

This guide will show you how to define access policies for your workload. For app <MY-APP> to be able to receive incoming requests from <MY-OTHER-APP> in the same namespace, this specification is…

Set up Faro

Set up Grafana Faro in your frontend application for real user monitoring, error tracking, and tracing.

Set up Faro with Next.js

Set up Grafana Faro in a Next.js application using the App Router.

Setup command line access

This guide shows you how to set up command line tools for accessing Nais clusters Follow Googles instructions on how to install gcloud for your OS

Show Grafana on infoscreen

How to show Grafana on an infoscreen

Shrink Cloud SQL disk size

This page describes how to shrink the disk size of a Cloud SQL instance. If something goes wrong, restore from the manual backup you created in step 2. See the Google Cloud Console for restore…

Sourcemap deobfuscation

How sourcemap deobfuscation works for frontend error stack traces.

Templating

In nais/deploy we use Handlebars 3.0 syntax as templating language. Both the template and variable file supports either YAML or JSON syntax.

Trace context propagation

Learn how to propagate trace context across process boundaries in a few common scenarios.

Triage an issue

Resolve, ignore, and assign issues in Nais APM, and understand regressions, mutes, and how triage state is shared across your team.

Troubleshooting

When you get a topic authorization failed error in your application, it means that the application has authenticated correctly with the cluster, but does not have the necessary permissions to access…

Troubleshooting

When something is wrong with your application, these kubectl commands should be the first things you check out:

Troubleshooting naisdevice

Restart your default browser.

Uninstall naisdevice

Update naisdevice

Upgrade major version

When the OpenSearch instance was created, it was set up with the major version that was current at the time. You can upgrade the OpenSearch instance to a newer major version via Nais Console.

Upgrade major version

This page describes how to upgrade the major version of your PostgreSQL database. Before doing a major version upgrade, consult the PostgreSQL Release Notes for any preparation that needs to be done.

Upgrade major version

This page describes how to upgrade the major version of your PostgreSQL database. Before doing a major version upgrade, consult the Google Cloud SQL documentation for any preparation that needs to be…

Upload assets to the CDN

This how-to guide shows you how to upload assets to the CDN. In your Github Workflow, add the following step to upload your assets to the CDN.

Use a config in your workload

This how-to guide shows you how to reference and use a config in your workload. A config can be made available as environment variables or files, or both.

Use a secret in your workload

This how-to guide shows you how to reference and use a secret in your workload. A secret can be made available as environment variables or files, or both.

Use log patterns during an incident

Collapse thousands of log lines into a handful of patterns in the Nais APM Logs tab to spot what's new or spiking during an incident.

Use OpenSearch in your workload

This guide will show you how to connect your workload to a previously created OpenSearch instance. In your workload manifest, add the following lines to reference the OpenSearch instance:

Use Valkey in your workload

This guide will show you how to connect your workload to a previously created Valkey instance. In your workload manifest, add the following lines to reference the Valkey instance:

Using BigQuery from your application

When connecting your BigQuery client you need to specify the project ID and the dataset ID. The project ID is available in the GCP_TEAM_PROJECT_ID environment variable. There's no automatic…

Using Kafka Streams with internal topics

This guide will show you how to use Kafka Streams with internal topics. Select a pool from one of the available pools.

Using the image outside of Nais

When using the nais/docker-build-push action, the image is pushed to a registry that is meant for use within the Nais platform. If you wish to use this image for anything else than deploying with the…

View logs from the command line

View logs from the command line using kubectl.

Workaround for password synchronization issues

We recommend using nais-cli for rotating password for your Postgres database user. Retrieve the password from the secret google-sql-MYAPP in your namespace (the password is base64 encoded):