Views: 902
Number of votes: 8
Average rating:

Getting started with deployment API in DXC

We just have released Deployment API in DXC-S as an Open Beta program. This feature allows partners and customers to automate deployment to DXC environments via API. 

There are two ways to deploy code changes via API: 

  1. Using a source environment - this is a traditional way to push changes in DXC. The application code is deployed to the Integration environment using any preferred tool supported by Azure Web Apps, and then get promoted to the Preproduction environment, and after that to the Production environment. The deployment flow is sequential.
  2. Using code packages - this is a new method. It requires to package your application code as a NuGet package first, and then it can be deployed to any environment. The deployment flow is much more flexible, but with great powers comes great responsibility, so we highly recommend to deploy your package to any non-production environment first before deploying it to Production.

It is possible to mix both ways, but it worth mentioning that we see the code packages as a primary way of doing deployments in the future.

How do I get started?

First, you will need to get Deployment API credentials. You can generate it using the DXC-S Management portal. The API credentials are specific per target environment. So if you are planning to deploy from Integration to Preproduction environment, you need to provide API credentials for Preproduction.

Next, install EpiCloud PowerShell module.

Now we are ready to start our first deployment via API. Let's deploy a CMS site from Integration to Preproduction. Open a PowerShell prompt and use the commands listed below.

The Import-Module command makes EpiCloud cmdlets available in the current PowerShell prompt:

Import-Module EPiCloud

The Connect-EpiCloud command stores API credentials in the console session, so we don't need to specify it again with every command:

Connect-EpiCloud -ClientKey <...> -ClientSecret <...>

And the Start-EpiDeployment will kick-off a deployment process:

Start-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -SourceApp cms -SourceEnvironment Integration -TargetEnvironment Preproduction

The command will respond with the current deployment status and deployment id:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : InProgress
startTime          : 2019-10-29T16:00:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The deployment id is needed to get the deployment status and to complete or reset the deployment. In order to get the deployment status use Get-EpiDeployment command:

Get-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

Once the first stage of the deployment is finished, we can validate the site on the deployment slot. The URL to the slot can be found in the validationLinks property in the Get-Deployment command response:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : AwaitingVerification
startTime          : 2019-10-29T16:10:14.198Z
endTime            :
percentComplete    : 100
validationLinks    : {http://sevodeploy275uzuprep-slot.dxcloud.episerver.net/}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

Now we can either complete or reset the deployment. There are two corresponding commands for that:

Complete-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8 

or

Reset-EpiDeployment -ProjectId ae874a90-08de-4a03-a865-aaf500f4830e -Id 5eec46c4-df99-47e6-a6b9-aaf5010874f8

After running the Complete-EpiDeployment command we get the deployment status displayed:

id                 : 5eec46c4-df99-47e6-a6b9-aaf5010874f8
projectId          : ae874a90-08de-4a03-a865-aaf500f4830e
status             : Completing
startTime          : 2019-10-29T16:20:51.123Z
endTime            :
percentComplete    : 0
validationLinks    : {}
deploymentWarnings : {}
deploymentErrors   : {}
parameters         : @{targetEnvironment=Preproduction; sourceEnvironment=Integration; sourceApps=System.Object[]; maintenancePage=False; includeBlob=False; includeDb=False}

The Complete-EpiDeployment command swaps the slot and deployment is now completed!

If you want to learn more, you can find a detailed description of all commands provided with the EpiCloud module in the documentation.

Using Azure DevOps? This blog post describes how to configure a continuous delivery pipeline with DXC-S.

Oct 29, 2019

Eric Markson
(By Eric Markson, 10/29/2019 8:19:44 PM)

This is absolutely awesome. I cannot wait to start using this! 

Ravindra S. Rathore
(By Ravindra S. Rathore, 10/30/2019 6:50:11 AM)

Great, very excited to use this in future. 

Stefan Holm Olsen
(By Stefan Holm Olsen, 10/30/2019 7:53:21 AM)

This so cool!

For the code package approach, do you think it would be possible to integrate it with TeamCity or Octopus Deploy?

Darren S
(By Darren S, 10/30/2019 8:11:31 AM)

Awesome! Thank you Episerver! 

Sergii Vorushylo
(By Sergii Vorushylo, 10/30/2019 8:58:21 AM)

@Stefan yes, of course, it is possible. And we are planning to provide more examples of how to do it. 

Tien Quach
(By Tien Quach, 10/31/2019 6:16:36 AM)

Nice feature!

Darren Sunderland
(By Darren Sunderland, 11/1/2019 1:06:37 PM)

I have had a play with this in our integration site but after running the command Complete-EpiDeployment, I get the status displayed as specified but the process never completes - or at least hasn't completed after 2 hours! 

Checking the status with Get-EpiDeployment shows that the deployment is still in the completing phase, leaving the maintenance page being displayed for the site.

Running either of the commands Complete-EpiDeployment or Reset-EpiDeployment, and I get an error stating that a prior deployment is in progress. Thus leaving me unable to progress any further.

I got our integration site back up by publishing from Visual Studio, but due to the status being stuck we are currently not able to deploy to pre-production or production via the PaaS portal.

Sergii Vorushylo
(By Sergii Vorushylo, 11/3/2019 8:57:39 PM)

@Darren sorry, this is definitely not the experience we are aiming for. I have checked the logs, and it seems there was an issue with the underlying infrastructure - the Complete job hasn't started for several hours for some reason, we will investigate a possible cause. Regarding the deployment status, it will timeout after about two hours so that a new deployment can be started. I checked your project, and it is not blocked anymore, the deployment to integration is marked as failed due timeout as expected. Please, do not hesitate to contact Episerver support in order to get help if you face with deployment issues again. 

Darren Sunderland
(By Darren Sunderland, 11/6/2019 10:26:48 AM)

@Sergii ths issue is now resolved and the deployment pipeline works all the way through the stack to production.

Please login to comment.