how-to
108 pagesAccessing 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…
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.
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 CLI.
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.
Change your Cloud SQL instance
Nais no longer provides database migration tooling. Choose the procedure for the change you need. Upgrade PostgreSQL on your existing instance. You do not need to migrate to a new instance. Plan for…
Communicate with other workloads
This guide shows you how to communicate with other workloads inside the same environment or cluster via service discovery.
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.
Connect to Postgres as a personal user
Use this how-to to connect to a Postgres database with your personal user, for ad-hoc queries and inspection.
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 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 an instance of BigQuery
Below is a minimal working example for a Nais Application manifest.
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 OpenSearch with GitHub Actions
Create .nais/opensearch.yaml: Change the name and configuration for your needs. See the complete generated example and OpenSearch manifest reference.
Create Postgres
Create a Postgres database. Provisioning continues asynchronously. Follow the status on the database's page in Nais Console.
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.
Create Valkey with GitHub Actions
Create .nais/valkey.yaml: Change the name and configuration for your needs. See the complete generated example and Valkey manifest reference.
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 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 Postgres
Deleting a Postgres irreversibly removes the whole instance with all its branches and data. Remove uses.postgres from all workloads that reference the database and deploy them. If the Postgres…
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…
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.
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 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 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 a platform-managed secret value using the CLI
This guide shows you how to look up and retrieve the value of a platform-managed secret for one of your workloads using the Nais CLI.
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 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 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.
Legacy Cloud SQL migration (deprecated)
The CLI saves migration configuration in the cluster and launches Naisjobs running cloudsql-migrator <span class="emoji-icon"><svg xmlns="http://www.w3.org/2000/svg" width="16px" height="16px"…
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:
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…
Manage Postgres
Change CPU, memory, disk size or high availability. PostgreSQL 18 is the only supported major version in preview; the CLI update command does not change the major version.
Metrics and alerts for logs
Use Loki-derived metrics to monitor log patterns and create Prometheus alerts.
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
Use your personal Google account to access a Cloud SQL database. Database privileges and login access are separate: prepare grants PostgreSQL privileges, but does not create an IAM database user or…
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
Redirect a client
The Nais platform support two ways to exposing your application, either via an Ingress resource, or through service discovery. This means that we also support two ways to redirect your application.
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:
Restore a database from a daily backup
This page describes how to restore a Cloud SQL Postgres database from one of the automated daily backups that Nais takes of your instance.
Restore a Postgres branch from backup
The restore creates a new, writable branch from a point in time covered by the source branch's backups. It does not change your workloads.
Schema validation and auto-completion
Use a YAML editor with SchemaStore support to get validation and auto-completion for Nais manifests. The editor schema covers supported resources in the Nais manifest format.
Set up a complete deploy pipeline
This guide shows the recommended setup for deploying an application to several environments with the Nais CLI. It builds on Build and deploy with GitHub Actions, adding environment mixins for…
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
Shrink Cloud SQL disk size
Shrink storage on your existing instance using gcloud. Follow Google's storage shrink procedure <span class="emoji-icon"><svg xmlns="http://www.w3.org/2000/svg" width="16px" height="16px" viewBox="0…
Sourcemap deobfuscation
How sourcemap deobfuscation works for frontend error stack traces.
Templating (deprecated)
The legacy nais/deploy action uses 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.
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 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 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 Postgres in a workload
Add the database to your Application or Job manifest in the same team and environment: Replace <POSTGRES-NAME> with the database name you used in Create Postgres, then deploy the workload as usual.…
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):