diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 556da86a8..90480b692 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -85,6 +85,8 @@ Generic Start ** xref:fleet-management/deployment-details.adoc[Deployment details] ** xref:fleet-management/procedures.adoc[Plugin procedures] ** xref:fleet-management/data.adoc[Data transparency] +** xref:fleet-management/aura-api.adoc[Aura API] +** xref:fleet-management/aura-cli.adoc[Aura CLI] * xref:apoc.adoc[APOC support] diff --git a/modules/ROOT/pages/fleet-management/aura-api.adoc b/modules/ROOT/pages/fleet-management/aura-api.adoc new file mode 100644 index 000000000..12156ebcf --- /dev/null +++ b/modules/ROOT/pages/fleet-management/aura-api.adoc @@ -0,0 +1,53 @@ += Aura API + +This page describes how to use the Aura API to manage Fleet Manager resources programatically. + +For instructions on how to use the Aura API, please read the documentation at xref:api/overview.adoc[API Documentation] + +The docs for the Aura API specs can be found at link:{neo4j-docs-base-uri}/aura/platform/api/specification/?urls.primaryName=Aura%20v2beta1[API Specification] + +If you would rather manage the Fleet Manager resources through the Aura CLI, you can find instructions for that here xref:./aura-cli.adoc[Aura CLI documentation] + +== Managing deploymments + +The Aura API allows for the creation and deletion of deployments, fetching information about deployments and managing tokens for deployments. + +All steps in the document assume that you already have a running Neo4j database that you want to manage through Fleet Manager. + +Documentation for setting up your Neo4j database with the Fleet Manager plugin can be found from the following pages: + +** Documentation for installing a Neo4j database can be found at: link:https://neo4j.com/docs/operations-manual/current/installation/[Installation] +** Documentation for installing the Fleet Manager plugin in your database: xref:./setup.adoc#_set_up_the_plugin[Plugin setup] + +All endpoints start with /organizations/:organization_id/projects/:project_id/, this will be left out for clarity and brevity. + +Creating and registering a Fleet Manager deployment is done in three parts. + +* Create a deployment. +** Send a post request to the `/deployments` endpoint supplying a `name` and an optional `connection_url` in the body. The response will hold the created deployment ID that will then be used when creating a token for the deployment. + +[source, shell] +---- +curl --request 'POST' https://api.neo4j.io/v2beta1/organizations/$YOUR_ORG_ID/projects/$YOUR_PROJECT_ID/deployments \ + --header 'accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer $YOUR_AURA_API_TOKEN" \ + --data '{"connection_url": "$OPTIONAL_CONNECTION_URL", "name": "$DEPLOYMENT_NAME"}' +---- + +* Create a token for the deployment. +** Send a post request to the `/deployments/:deployment_id/token` endpoint. The token will be created as an auto rotating token with a three month rotation interval. + +[source, shell] +---- +curl --request 'POST' https://api.neo4j.io/v2beta1/organizations/$YOUR_ORG_ID/projects/$YOUR_PROJECT_ID/deployments/$DEPLOYMENT_ID/token \ + --header 'accept: application/json' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer $YOUR_AURA_API_TOKEN" +---- + +* Register the token to your Neo4j database. +** Connect to your Neo4j database and register the newly created token to the database with `call fleetManagement.registerToken('$TOKEN');` + +* Refresh token +** If you need to rotate a token before the token rotates automatically, you can refresh the token by sending a PATCH request to the `/deployments/:deployment_id/token` endpoint. diff --git a/modules/ROOT/pages/fleet-management/aura-cli.adoc b/modules/ROOT/pages/fleet-management/aura-cli.adoc new file mode 100644 index 000000000..1aca7d251 --- /dev/null +++ b/modules/ROOT/pages/fleet-management/aura-cli.adoc @@ -0,0 +1,54 @@ += Aura CLI + +This page describes how to manage Fleet Manager deployments through the Aura CLI. For general instructions on how to use the cli, please read the xref:aura-cli/index.adoc[Aura CLI documentation]. + +The CLI has access to all of the same functionalities as the Aura API and requires you to have a valid Aura API key configured in the CLI. + +Currently all Fleet Manager commands are still under the Aura API v2 beta branch so you need to set the CLI into beta mode with the following command `aura-cli config set beta-enabled true`. + +The top level command for accessing Fleet Manager resources through the CLI is `deployment`. All commands have a help function to list the required arguments, required and optinal flags and all shorthands for the flags. + +== Registering a new deployment + +Registering a new deployment happens in three steps. The guide assumes that you already have a running Neo4j database that you want to register with Fleet Manager. + +* Create a new deployment +** `aura-cli deployment create --name $DEPLOYMENT_NAME --connection_url $OPTIONAL_CONNECTION_URL --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Create a new token for the deployment. The token will be an auto rotating token with a three month rotation interval. +** `aura-cli deployment token create --deployment-id $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Register the deployment +** Connect to your Neo4j database and register the newly created token to the database with `call fleetManagement.registerToken('$TOKEN');` + +*** Register a docker container from a cli: `docker exec -it $CONTAINER_NAME ./bin/cypher-shell -a $SERVICE_NAME:$PORT -d system -u $NEO4J_USERNAME -p$NEO4J_PASSWORD "call fleetManagement.registerToken('"$TOKEN"');"` + + +== Fetching deployments + +* List all deployments +** `aura-cli deployment list --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Get details of a deployment +** `aura-cli deployment get $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Get all databases for a deployment +** `aura-cli deployment database list --deployment-id $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Get all servers for a deployment +** `aura-cli deployment server list --deployment-id $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Get all databases for a deployment server +** `aura-cli deployment server database list --deployment-id $DEPLOYMENT_ID --server-id $SERVER_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +== Other useful commands + +* Delete a deployment +** `aura-cli deployment delete $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Delete a deployment token +** `aura-cli deployment token delete --deployment-id $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` + +* Refresh a deployment token +** `aura-cli deployment token update --deployment-id $DEPLOYMENT_ID --organization-id $YOUR_ORG_ID --project-id $YOUR_PROJECT_ID` +** After creating the new deployment token, register it into the same database with the `registerToken` call. \ No newline at end of file diff --git a/modules/ROOT/pages/fleet-management/setup.adoc b/modules/ROOT/pages/fleet-management/setup.adoc index 8d95ca549..9abaa970d 100644 --- a/modules/ROOT/pages/fleet-management/setup.adoc +++ b/modules/ROOT/pages/fleet-management/setup.adoc @@ -31,7 +31,7 @@ The next step of the wizard walks you through the process of adding the fleet ma Neo4j *2025.09+* comes bundled with the fleet management plugin in the _products_ folder. For earlier versions of Neo4j, you need to download the plugin. -Follow the link in the wizard to download the plugin. +Follow the link in the wizard to download the plugin or download it directly from the link:https://neo4j.com/deployment-center/#tools-tab[Deployment Center]. Neo4j Fleet management plugin has the name format `neo4j-fleet-management-plugin-VERSION-NEO4J_VERSION.jar`. Select the appropriate plugin for your Neo4j version.