Project: Lagoon (App Definition and Development / Application Definition & Image Build)
File: graphql-queries.md

Direct API interactions in Lagoon are done via . In order to authenticate with the API, we need a JWT (JSON Web Token) that allows us to use the GraphQL API as admin. To generate this token, open the terminal of the `storage-calculator` pod via your Kubernetes UI, or via kubectl and run the following command: ```bash title="Generate JWT token." ./create_jwt.py ``` This will return a long string which is the JWT token. Make a note of this, as we will need it to send queries. We also need the URL of the API endpoint, which can be found under "Ingresses" in your Kubernetes UI or via kubectl on the command line. Make a note of this endpoint URL, which we will also need. To compose and send GraphQL queries, we recommend , a desktop GraphQL client with features such as autocomplete. To continue with the next steps, install and start the app. Under "GraphQL Endpoint", enter the API endpoint URL with `/graphql` on the end. Then click on "Edit HTTP Headers" and add a new header: "Header name": `Authorization` "Header value": `Bearer [JWT token]` (make sure that the JWT token has no spaces, as this would not work) Press ESC to close the HTTP header overlay and now we are ready to send the first GraphQL request! Enter this in the left panel ```graphql title="Running a query" query allProjects{ allProjects { name } } ``` And press the button (or press CTRL+ENTER). If all went well, your first GraphQL response should appear shortly afterwards in the right pane. Let's create the first project for Lagoon to deploy! For this we'll use the queries from the GraphQL query template in . For each of the queries (the blocks starting with `mutation {`), fill in all of the empty fields marked by TODO comments and run the queries in GraphiQL.app. This will create one of each of the following two objects: `kubernetes` : The Kubernetes (or Openshift) cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own Kubernetes cluster, but also to any Kubernetes cluster anywhere in the world. `project` : The Lagoon project to be deployed, which is a Git repository with a `.lagoon.yml` configuration file committed in the root. In Lagoon, each developer authenticates via their SSH key(s). This determines their access to: The Lagoon API, where they can see and edit projects they have access to. Remote shell access to containers that are running in projects they have access to. The Lagoon logging system, where a developer can find request logs, container logs, Lagoon logs and more. To allow access to the project, we first need to add a new group to the API: ```graphql title="Add group to API" mutation { addGroup ( input: { name: "" } ) { id name } } ``` Then we need to add a new user to the API: ```graphql title="Add new user to API" mutation { addUser( input: { email:

firstName: "Michael" lastName: "Schmid" comment: "CTO" } ) { id } } ``` Then we can add an SSH public key for the user to the API: ```graphql title="Add SSH public key for the user to API" mutation { addSshKey( input: { name: "" keyValue: "" keyType: SSH_RSA user: { id:"0", email:"michael.schmid@example.com" } } ) { id } } ``` After we add the key, we need to add the user to a group: ```graphql title="Add user to group" mutation { addUserToGroup ( input: { user: { email: "" } group: { name: "" } role: OWNER } ) { id name } } ``` After running one or more of these kinds of queries, the user will be granted access to create tokens via SSH, access containers and more. If you want to know what is going on during a deployment, we suggest configuring notifications for your project, which provide: Push notifications Build start information Build success or failure messages And many more! As notifications can be quite different in terms of the information they need, each notification type has its own mutation. As with users, we first add the notification: ```graphql title="Add notification" mutation { addNotificationSlack( input: { name: "" channel: "" webhook: "" } ) { id } } ``` After the notification is created, we can now assign it to our project: ```graphql title="Assign notification to project" mutation { addNotificationToProject( input: { notificationType: SLACK project: "" notificationName: "" contentType: DEPLOYMENT/PROBLEM notificationSeverityThreshold "NONE/UNKNOWN/NEGLIGIBLE/LOW/MEDIUM/HIGH/CRITICAL } ) { id } } ``` Now for every deployment you will receive messages in your defined channel. !!! Note In Lagoon, both `addKubernetes` and `addOpenshift` can be used for both Kubernetes and OpenShift targets - either will work interchangeably. The cluster to which Lagoon should deploy. ```graphql title="Add Kubernetes target" mutation { addKubernetes( input: { name: "" consoleUrl: "" token: "" } ) { name id } } ``` This query will add a group to a project. Users of that group will be able to access the project. They will be able to make changes, based on their role in that group. ```graphql title="Add a group to a project" mutation { addGroupsToProject ( input: { project: { name: "" } groups: { name: "" } } ) { id } } ``` This query adds a new Lagoon project to be deployed, which is a Git repository with a `.lagoon.yml` configuration file committed in the root. If you omit the `privateKey` field, a new SSH key for the project will be generated automatically. If you would like to reuse a key from another project. you will need to supply the key in the `addProject` mutation. ```graphql title="Add a new project" mutation { addProject( input: { name: "" privateKey: "" kubernetes: 0 gitUrl: "" branches: "" productionEnvironment: "" } ) { name kubernetes { name id } gitUrl branches pullrequests } } ``` This is a good query to see an overview of all projects, clusters and groups that exist within our Lagoon. ```graphql title="Get an overview of all projects, clusters, and groups" query { allProjects { name gitUrl } allKubernetes { name id } allGroups{ id name members { user { id firstName lastName } role } groups { id name } } } ``` If you want a detailed look at a single project, this query has been proven quite good: ```graphql title="Take a detailed look at one project" query { projectByName( name: "" ) { id branches gitUrl pullrequests productionEnvironment notifications(type: SLACK) {

on NotificationSlack { name channel webhook id } } environments { name deployType environmentType } kubernetes { id } } } ``` Don't remember the name of a project, but know the Git URL? Search no longer, there is a GraphQL query for that: ```graphql title="Query project by Git URL" query { projectByGitUrl(gitUrl: "git@server.com:org/repo.git") { name } } ``` The Lagoon GraphQL API can not only display objects and create objects, it also has the capability to update existing objects, using . Update the branches to deploy within a project: ```graphql title="Update deploy branches." mutation { updateProject( input: { id: 109, patch: { branches: "^(prod|stage|dev|update)$" } } ) { id } } ``` Update the production environment within a project: !!! warning This requires a redeploy in order for the changes to be reflected in the containers. ```graphql title="Update prod environment" mutation { updateProject( input: { id: 109, patch: { productionEnvironment: "main" } } ) { id } } ``` You can also combine multiple changes at once: ```graphql title="Update prod environment and set deploy branches." mutation { updateProject( input: { id: 109 patch: { productionEnvironment: "main" branches: "^(prod|stage|dev|update)$" } } ) { id } } ``` You can also use the Lagoon GraphQL API to delete an environment. You'll need to know the project name and the environment name in order to run the command. ```graphql title="Delete environment." mutation { deleteEnvironment( input: { name:"" project:"" execute:true } ) } ``` Want to see what groups and users have access to a project? Want to know what their roles are? Do I have a query for you! Using the query below you can search for a project and display the groups, users, and roles that are assigned to that project. ```graphql title="Query groups, users, and roles assigned to project" query search{ projectByName( name: "" ) { id, branches, productionEnvironment, pullrequests, gitUrl, kubernetes { id }, groups{ id name groups { id name } members { role user { id email } } } } } ``` Project metadata can be assigned using arbitrary key/value pairs. Projects can then be queried by the associated metadata; for example you may categorize projects by type of software, version number, or any other categorization you may wish to query on later. Updates to metadata expect a key/value pair. It operates as an `UPSERT`, meaning if a key already exists the value will be updated, otherwise inserted. You may have any number of k/v pairs stored against a project. ```graphql title="Add a key/value pair to metadata" mutation { updateProjectMetadata( input: { id: 1, patch: { key: "type", value: "saas" } } ) { id metadata } } ``` Queries may be by `key` only (e.g return all projects where a specific key exists) or both `key` and `value` where both key and value must match. All projects that have the `version` tag: ```graphql title="Query by metadata" query projectsByMetadata { projectsByMetadata(metadata: [{key: "version"] ) { id name } } ``` All projects that have the `version` tag, specifically version `8`: ```graphql title="Query by metadata" query projectsByMetadata { projectsByMetadata(metadata: [{key: "version", value: "8"] ) { id name } } ``` Metadata can be removed on a per-key basis. Other metadata key/value pairs will persist. ```graphql title="Remove metadata" mutation { removeProjectMetadataByKey ( input: { id: 1, key: "version" } ) { id metadata } } ```