console-backend-service

README

Console Backend Service

Overview

This project includes a server that exposes the GraphQL API for all Kyma UIs. It consumes the Kubernetes API using the K8S Go client. This document describes how to use the application and how to develop new features in this project.

NOTE: The description of the application configuration, the project structure, the architecture, and other project-specific details are located in the docs directory.

See the GraphQL schema definition file for the list of supported queries and mutations.

Prerequisites

Use the following tools to set up the project:

• Go
• Docker

Usage

Run a local version

To start the application without building the binary, set your $KUBECONFIG environment variable, and run:

APP_KUBECONFIG_PATH=$KUBECONFIG APP_DEBUG_DOMAIN={kymaDomain} go run main.go

For the descriptions of the available environment variables, see the Configuration document.

The service listens on port 3000. Open http://localhost:3000 to see the GraphQL console in your browser.

Use GraphQL console on cluster

Before using the console on a cluster, set a valid token for all requests. Click the Header option at the bottom of the GraphQL console and paste this snippet:

{
  "Authorization": "Bearer {YOUR_BEARER_TOKEN}"
}

After you paste the custom HTTP header, reload the page. GraphQL console allows you to access the schema documentation and test queries, mutations, and subscriptions.

Build a production version

To build the production Docker image, run this command:

docker build {image_name}:{image_tag}

The variables are:

• {image_name} - name of the output image (default: console-backend-service)
• {image_tag} - tag of the output image (default: latest)

Certificate error

When you run the UI API Layer project, you can get the following error:

oidc.go:222] oidc authenticator: initializing plugin: Get https://dex.kyma.local/.well-known/openid-configuration: x509: certificate signed by unknown authority

This error can occur if you use Go version 1.11.5 or lower on macOS. Try upgrading to version 1.11.6 or higher. For details, see this issue.

Development

Install dependencies

This project uses go modules as a dependency manager. To install all required dependencies, use the following commands:

go mod download
go mod vendor

Generate code from GraphQL schema

This project uses the GQLGen library, which improves development by generating code from the GraphQL schema definition.

1. Define types and their fields in /internal/gqlschema/*.graphql files using the Schema Definition Language.
2. From the project directory, run the code generator with the go run github.com/99designs/gqlgen ./internal/domain command.
3. Navigate to the /internal/gqlschema/ directory.
4. Find newly generated methods in the ResolverRoot interface located in ./schema_gen.go.
5. Implement resolvers in specific domains according to the project structure and rules in this guide. Use generated models from ./models_gen.go in your business logic. If you want to customize them, move them to a new file in the gqlschema package and include in the ./config.yml file.

To use advanced features, such as custom scalars, read the documentation of the used library.

Run tests

To run all unit tests, execute the following command:

go test ./...

Verify the code

To check if the code is correct and you can push it, use the make command. It builds the application, runs tests, checks the status of the vendored libraries, runs the static code analysis, and checks if the formatting of the code is correct.

To automatically format the incorrect code, use the make format command.