Deploy and manage services
This guide will walk you through deploying Akka services using the Akka Console and the Akka CLI. By the end, you’ll be able to deploy, check the status, update, and remove services.
Build container image
Build a container image of the service:
mvn clean install -DskipTestsBy default, the maven build will produce images with the following format:container-name:tag-name where the container name is theartifactId and the tag name is theversion plus the build timestamp.
The docker build output in maven will print something similar to the following:
DOCKER> Tagging image shopping-cart:1.0-SNAPSHOT-20241028102843 successful!Deploying a service
Services can be deployed via the Akka CLI.
To deploy your service, use the following command. Replacemy-service with your service name and update the container name and tag from themvn install:
akka service deploy my-service container-name:tag-name --pushYour service will now begin deploying.
The--push flag will push the container image to the Akka Container Registry before deploying the service. If your project has more than one region, the image will be pushed to each region ACR and deployed in all regions. If you are not using ACR, you first need to push the image to the container registry you are using.Seepushing to ACR andpushing to external container registry for more information. |
| To combine deploying a service with relevant settings, Akka supports deploying with service descriptors (see below). |
Checking service status
You can verify the deployment status of your service in the Akka Console or with the Akka CLI:
- Akka CLI
Verify the service status from the command line with this command:
akka service listA service status can be one of the following:
Ready: All service instances are up-to-date and fully available.
UpdateInProgress: Service is updating.
Unavailable: No service instances are available.
PartiallyReady: Some, but not all, service instances are available.
- Akka Console
Open theAkka Console.
Navigate to theProject where the Service is deployed.
Look for theService card of the Service, it shows the status.
A service status can be one of the following:
Ready: All service instances are up-to-date and fully available.
Update In Progress: Service is updating.
Unavailable: No service instances are available.
Partially Ready: Some, but not all, service instances are available.
How to update a deployed service
If you need to update your service with a new container image:
Make changes to your service andpackage them into anew container image, seeBuild container image.
Deploy the updated image by passing the new tag:
akka service deploy my-service container-name:tag-name-2 --push
Akka will perform a rolling update, replacing old instances with new ones without downtime.
The--push flag will push the container image to the Akka Container Registry before deploying the service. If your project has more than one region, the image will be pushed to each region ACR and deployed in all regions. If you are not using ACR, you first need to push the image to the container registry you are using.Seepushing to ACR andpushing to external container registry for more information. |
Pushing to Akka Container Registry
Pushing images to the Akka Container Registry (ACR) works similarly to other Docker registries, with the added feature that Akka supports multi-region deployments. When deploying to multiple regions, each configured region requires its own ACR. The Akka CLI manages this process automatically.
To push your images to the Akka Container Registry (ACR), use the following command:
akka container-registry push container-name:tag-nameThis command will create new tags specifically formatted for ACR, prepending the ACRURL, theorganization, and theproject names to the image before pushing it.
For example, if your project has two regions with ACRsacr.us-east-1.akka.io andacr.us-east-2.akka.io, the command will push to:
acr.us-east-1.akka.io/my-organization/my-project/container-name:tag-nameacr.us-east-2.akka.io/my-organization/my-project/container-name:tag-name
After pushing to all regions, the CLI will display the primary region’s image path, which should be used for service deployment:
When deploying an Akka service, use the primary region image tag:acr.us-east-1.akka.io/my-organization/my-project/container-name:tag-nameACR image paths
Images in ACR follow a hierarchical structure and can be scoped to either a single project or an entire organization:
For single-project availability, the image path must include both the organization and project names:
my-organization/my-project/container-name:tag-nameTo make an image available acrossall projects within an organization, use only the organization name in the image path:
my-organization/container-name:tag-name
In ACR, this structure reflects Akka’s organizational layout, where an organization can manage multiple projects that host images. Images stored at the organizational root can be deployed in any project within that organization.
As mentioned earlier, the Maven build will produce images with the formatcontainer-name:tag-name (withoutorganization andproject segments). When pushing images without the organization and project segments, the Akka CLI will populate these segments based on your currentorganization andproject.
If desired, you can configure Maven to build images for a specificorganization ororganization/project. To do this, configure thedocker.image property in your pom.xml:
<properties> <docker.image>my-organization/my-project/container-name</docker.image></properties>Pushing to external container registry
If you are not using ACR, usedocker push command instead.
docker push container-uri/container-name:tag-nameEnsure that your chosen container registry is accessible to all regions in your project.
For further details, seeexternal container registries.
Using service descriptors
Akka services can also be described and managed withYAML service descriptors. SeeService Descriptor reference.
You can deploy your service using a service descriptor.For this you need at least the image, which you can get bybuilding the container image and thenpushing it to the container registry:
akka container-registry push container-name:tag-nameOnce pushed, you need to use the suggested image from the command’s output in your service descriptor, for example:
name: my-serviceservice: image: acr.us-east-1.akka.io/my-organization/my-project/container-name:tag-name env: - name: SOME_VARIABLE value: some valueYou must add the primary region image tag fromakka container-registry push output. |
To apply this descriptor, run:
akka service apply -f my-service.yamlYou can also export an existing service’s descriptor for reference or editing:
akka service export my-service -f my-service.yamlRedeploying with a descriptor
After editing the service descriptor (e.g.,my-service.yaml), redeploy it with:
akka service apply -f my-service.yamlEditing the service descriptor in place
Once you havedeployed your service, you can also modify it by editing its service descriptor:
akka service edit my-serviceRemoving a deployed service
To delete a service and free its resources, run the following command, replacingmy-service with the name of the service you want to remove:
akka service delete my-serviceThe service will be deleted, and its resources will be freed.
During development, with changing domain models, it may be useful to delete a serviceincluding its data. To delete already stored data and the service, use the |
Conclusion
You now know how to deploy, verify, update, and remove Akka services using the Akka CLI. Continue experimenting with different configurations and commands to further enhance your services.