L
L
Lagoon
Search…
GraphQL API

Running GraphQL queries

Direct API interactions in Lagoon are done via GraphQL.
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 auto-idler pod via the OpenShift UI and run the following command:
1
./create_jwt.sh
Copied!
This can also be done with the oc command:
1
oc -n lagoon-main rsh dc/auto-idler ./create_jwt.sh
Copied!
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 "Routes" in the OpenShift UI or oc get route api on the command line. Make a note of this endpoint URL, which we will also need.
To compose and send GraphQL queries, we recommend GraphiQL.app, 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!
Editing HTTP Headers in GraphiQL.
Enter this in the left panel
1
query allProjects{
2
allProjects {
3
name
4
}
5
}
Copied!
Running a query in GraphiQL.
And press the ▶️ button (or press CTRL+ENTER).
If all went well, your first GraphQL response should appear shortly afterwards in the right pane.

Creating the first project

Let's create the first project for Lagoon to deploy! For this we'll use the queries from the GraphQL query template in create-project.gql.
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:
    1.
    openshift : The OpenShift cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own OpenShift, but also to any OpenShift anywhere in the world.
    2.
    project : The Lagoon project to be deployed, which is a Git repository with a .lagoon.yml configuration file committed in the root.

Allowing access to the project

In Lagoon, each developer authenticates via their SSH key(s). This determines their access to:
    1.
    The Lagoon API, where they can see and edit projects they have access to.
    2.
    Remote shell access to containers that are running in projects they have access to.
    3.
    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:
1
mutation {
2
addGroup (
3
input: {
4
# TODO: Enter the name for your new group.
5
name: ""
6
}
7
) {
8
id
9
name
10
}
11
}
Copied!
Then we need to add a new user to the API:
1
mutation {
2
addUser(
3
input: {
5
firstName: "Michael"
6
lastName: "Schmid"
7
comment: "CTO"
8
}
9
) {
10
# TODO: Make a note of the user ID that is returned.
11
id
12
}
13
}
Copied!
Then we can add an SSH public key for the user to the API:
1
mutation {
2
addSshKey(
3
input: {
4
# TODO: Fill in the name field.
5
# This is a non-unique identifier for the SSH key.
6
name: ""
7
# TODO: Fill in the keyValue field.
8
# This is the actual SSH public key (without the type at the beginning and without the comment at the end, ex. `AAAAB3NzaC1yc2EAAAADAQ...3QjzIOtdQERGZuMsi0p`).
9
keyValue: ""
10
# TODO: Fill in the keyType field.
11
# Valid values are either SSH_RSA or SSH_ED25519.
12
keyType: SSH_RSA
13
user: {
14
# TODO: Fill in the userId field.
15
# This is the user ID that we noted from the addUser query.
16
id:"0",
18
}
19
}
20
) {
21
id
22
}
23
}
Copied!
After we add the key, we need to add the user to a group:
1
mutation {
2
addUserToGroup (
3
input: {
4
user: {
5
#TODO: Enter the email address of the user.
6
email: ""
7
}
8
group: {
9
#TODO: Enter the name of the group you want to add the user to.
10
name: ""
11
}
12
#TODO: Enter the role of the user.
13
role: OWNER
14
15
}
16
) {
17
id
18
name
19
}
20
}
Copied!
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.

Adding notifications to the project

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:
1
mutation {
2
addNotificationSlack(
3
input: {
4
# TODO: Fill in the name field.
5
# This is your own identifier for the notification.
6
name: ""
7
# TODO: Fill in the channel field.
8
# This is the channel for the message to be sent to.
9
channel: ""
10
# TODO: Fill in the webhook field.
11
# This is the URL of the webhook where messages should be sent, this is usually provided by the chat system to you.
12
webhook: ""
13
}
14
) {
15
id
16
}
17
}
Copied!
After the notification is created, we can now assign it to our project:
1
mutation {
2
addNotificationToProject(
3
input: {
4
notificationType: SLACK
5
# TODO: Fill in the project field.
6
# This is the project name.
7
project: ""
8
# TODO: Fill in the notification field.
9
# This is the notification name.
10
notificationName: ""
11
# TODO: OPTIONAL
12
# The kind notification class you're interested in defaults to DEPLOYMENT
13
contentType: DEPLOYMENT/PROBLEM
14
# TODO: OPTIONAL
15
# Related to contentType PROBLEM, we can set the threshold for the kinds of problems
16
# we'd like to be notified about
17
notificationSeverityThreshold "NONE/UNKNOWN/NEGLIGIBLE/LOW/MEDIUM/HIGH/CRITICAL
18
}
19
) {
20
id
21
}
22
}
Copied!
Now for every deployment you will receive messages in your defined channel.

Example GraphQL queries

Adding a new OpenShift target

In Lagoon 1.x addOpenshift is used for both OpenShift and Kubernetes targets. In Lagoon 2.x this will change.
The OpenShift cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own OpenShift, but also to any OpenShift anywhere in the world.
1
mutation {
2
addOpenshift(
3
input: {
4
# TODO: Fill in the name field.
5
# This is the unique identifier of the OpenShift.
6
name: ""
7
# TODO: Fill in consoleUrl field.
8
# This is the URL of the OpenShift console (without any `/console` suffix).
9
consoleUrl: ""
10
# TODO: Fill in the token field.
11
# This is the token of the `lagoon` service account created in this OpenShift (this is the same token that we also used during installation of Lagoon).
12
token: ""
13
}
14
) {
15
name
16
id
17
}
18
}
Copied!

Adding a group to a project

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.
1
mutation {
2
addGroupsToProject (
3
input: {
4
project: {
5
#TODO: Enter the name of the project.
6
name: ""
7
}
8
groups: {
9
#TODO: Enter the name of the group that will be added to the project.
10
name: ""
11
}
12
}
13
) {
14
id
15
}
16
}
Copied!

Adding a new project

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.
1
mutation {
2
addProject(
3
input: {
4
# TODO: Fill in the name field.
5
# This is the project name.
6
name: ""
7
# TODO: Fill in the private key field (replace newlines with '\n').
8
# This is the private key for a project, which is used to access the Git code.
9
privateKey: ""
10
# TODO: Fill in the OpenShift field.
11
# This is the id of the OpenShift to assign to the project.
12
openshift: 0
13
# TODO: Fill in the name field.
14
# This is the project name.
15
gitUrl: ""
16
# TODO: Fill in the branches to be deployed.
17
branches: ""
18
# TODO: Define the production environment.
19
productionEnvironment: ""
20
}
21
) {
22
name
23
openshift {
24
name
25
id
26
}
27
gitUrl
28
activeSystemsDeploy
29
activeSystemsRemove
30
branches
31
pullrequests
32
}
33
}
Copied!

List projects and groups

This is a good query to see an overview of all projects, OpenShifts and groups that exist within our Lagoon.
1
query {
2
allProjects {
3
name
4
gitUrl
5
}
6
allOpenshifts {
7
name
8
id
9
}
10
allGroups{
11
id
12
name
13
members {
14
# This will display the users in this group.
15
user {
16
id
17
firstName
18
lastName
19
}
20
role
21
}
22
groups {
23
id
24
name
25
}
26
}
27
}
Copied!

Single project

If you want a detailed look at a single project, this query has been proven quite good:
1
query {
2
projectByName(
3
# TODO: Fill in the project name.
4
name: ""
5
) {
6
id
7
branches
8
gitUrl
9
pullrequests
10
productionEnvironment
11
notifications(type: SLACK) {
12
... on NotificationSlack {
13
name
14
channel
15
webhook
16
id
17
}
18
}
19
environments {
20
name
21
deployType
22
environmentType
23
}
24
openshift {
25
id
26
}
27
}
28
}
Copied!

Querying a project by its Git URL

Don't remember the name of a project, but know the Git URL? Search no longer, there is a GraphQL query for that:
1
query {
2
projectByGitUrl(gitUrl: "[email protected]:org/repo.git") {
3
name
4
}
5
}
Copied!

Updating objects

The Lagoon GraphQL API can not only display objects and create objects, it also has the capability to update existing objects, using a patch object.
Update the branches to deploy within a project:
1
mutation {
2
updateProject(
3
input: { id: 109, patch: { branches: "^(prod|stage|dev|update)quot; } }
4
) {
5
id
6
}
7
}
Copied!
Update the production environment within a project:
This requires a redeploy in order for the changes to be reflected in the containers.
1
mutation {
2
updateProject(
3
input: { id: 109, patch: { productionEnvironment: "main" } }
4
) {
5
id
6
}
7
}
Copied!
You can also combine multiple changes at once:
1
mutation {
2
updateProject(
3
input: {
4
id: 109
5
patch: {
6
productionEnvironment: "main"
7
branches: "^(prod|stage|dev|update)quot;
8
}
9
}
10
) {
11
id
12
}
13
}
Copied!

Deleting Environments

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.
1
mutation {
2
deleteEnvironment(
3
input: {
4
# TODO: Fill in the name field.
5
# This is the environment name.
6
name:""
7
# TODO: Fill in the project field.
8
# This is the project name.
9
project:""
10
execute:true
11
}
12
)
13
}
Copied!

Querying a project to see what groups and users are assigned

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.
1
query search{
2
projectByName(
3
#TODO: Enter the name of the project.
4
name: ""
5
) {
6
id,
7
branches,
8
productionEnvironment,
9
pullrequests,
10
gitUrl,
11
openshift {
12
id
13
},
14
groups{
15
id
16
name
17
groups {
18
id
19
name
20
}
21
members {
22
role
23
user {
24
id
25
email
26
}
27
}
28
}
29
}
30
}
Copied!

Maintaining project metadata

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.

Add/update metadata on a project

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.
1
mutation {
2
updateProjectMetadata(
3
input: { id: 1, patch: { key: "type", value: "saas" } }
4
) {
5
id
6
metadata
7
}
8
}
Copied!

Query for projects by 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:
1
query projectsByMetadata {
2
projectsByMetadata(metadata: [{key: "version"] ) {
3
id
4
name
5
}
6
}
Copied!
All projects that have the version tag, specifically version 8:
1
query projectsByMetadata {
2
projectsByMetadata(metadata: [{key: "version", value: "8"] ) {
3
id
4
name
5
}
6
}
Copied!

Removing metadata on a project

Metadata can be removed on a per-key basis. Other metadata key/value pairs will persist.
1
mutation {
2
removeProjectMetadataByKey (
3
input: { id: 1, key: "version" }
4
) {
5
id
6
metadata
7
}
8
}
Copied!
Last modified 15d ago