System Center 2012 R2 Virtual Machine Role Authoring Guide - Resource Extension Package

Article
1/17/2024

This topic is part of the System Center 2012 R2 Virtual Machine Role Authoring Guide.

The Microsoft System Center team has validated this content as of Revision #3. We will continue to review any changes and periodically provide validations on later revisions as they are made. Please feel free to make any corrections or additions to this content that you think would assist other users.

Introduction

A Resource Extension is a reusable package that describes applications that are hosted within a Resource Definition. Each Resource Definition can reference one Resource Extension, and each extension can be referenced by more than definition.

Resource Extensions are packaged into a single file with the extension .resextpkg. If it contains an application payload, then these files are also included in the package.

The Resource Extension Package includes the following components:

Resource Extension File (RESEXT)
Application Payload

These components are illustrated in the following diagram and discussed in detail in the following sections.

Resource Extension File

A Resource Extension File (RESEXT) is a versioned template that describes how a resource should be installed and configured within a resource that is described by a Resource Definition File.

The contents of the Resource Extension Fileare illustrated in the following diagram and discussed in detail in the following sections.

Identification

Each Resource Extension must be uniquely identified by the following three properties. No two extensions may have the same values for these properties.

Name
Publisher
Version

Virtual Machine Roles support versioning so that the newer version of a template may be installed to supersede the previous version.

Example

The following JSON example shows the Identification section for a sample Resource Extension File called IIS_Demo_2:

"Name": "IIS_Demo_2",
"Publisher": "Microsoft",
"SchemaVersion": "1.0.0.0",
"Version": "1.0.0.0",
"ExtensionHostingContract": "MicrosoftCompute/VMRole/1.0.0.0",

Data Package

The Data Package section of the Resource Extension File defines the location in the package of the files for the application installation. The Location setting specifies the name of a folder in the Resource Extension Package that includes the application payload.

The following JSON example shows the Data Package section for a sample RESEXT. In this example, the Resource Extension package would need to include a folder called IISW2012 that contained the installation files for the application.

"DataPackage" : {
    "Location" : "IISWS2012",
    "Version" : "1.0.0.0" 
},

Resource Extension Parameters

Because a single Resource Extension can be used to provision multiple instances of a single resource, they can declare parameters which describe values that the Resource Definition must provide to customize the provisioning of a single instance of the resource. The Resource Definition specifies which parameters should be collected from the user by defining them in the View Definition.

The following JSON example shows the Resource Extension Parameters for a sample Resource Extension. In this example, the Resource Extension would require the Resource Definition to provide the value for a parameter called IISPort.

"ResourceExtensionParameters": [
    {
        "Name" : "IISPort",
        "Type" : "String",
        "Description" : "IIS Port"
    }
],

Resource Requirements

The Resource Requirements section of the Resource Extension File defines the requirements of the virtual hard disk used by the Virtual Machine Role. The administrator must ensure that at least one VHD is configured according to the documented requirements of the Resource Extension and then tagged with the required tags in order to identify it appropriately.

The following JSON example shows the Resource Requirements for a sample RESEXT. In this example, any VHDs to be used with the Virtual Machine Role would require the tags “WindowsServer2012” and “Datacenter”.

"ResourceRequirements": {
    "OSVirtualHardDiskRequirements": [
        "WindowsServer2012",
        "Datacenter"
    ]
},

Application Profile

The Application Profile section of the Resource Extension file describes the file and instructions necessary to install and configure the application. Different configuration is provided depending on whether the application runs on Windows or Linux.

For a Windows application, you can define the roles and features that are required to support the application. These are enabled in the operating system as part of the provisioning of the Virtual Machine Role. This feature is not available for a Linux application, and you must ensure that the operating system is appropriately configured on the OS VHD.

For either Windows or Linux applications, you also define the commands that must be run to perform the application installation. This command can leverage the files that are included in the application payload.

Application Payload

The Application Payload is the set of files that are required for installation of the application. In addition to installation files, this may include other resources such as scripts and installation packages. The Application Payload section of the Resource Extension file specifies a relative path and unique identifier for the payload of the application being installed. This relative path must correspond to a folder or file in the Data Package section of the file.

The following JSON example shows the Application Payload for a sample Resource Extension. A GUID is required for the identifier to ensure that it is unique. The Resource Extension Package would require a folder called IISConfiguration.cr under the IISW2012 folder, which is the folder specified in the Data Package section specified above.

"ApplicationPayload": [
    {
        "ID" : "123dbce1-8ccd-4fb1-af39-a2a3b69b4123",
        "RelativePath" : "IISConfiguration.cr"
    }        
],

Windows Application Profile

The Windows Application Profile section allows you define the installation requirements and the OS configuration requirements of one or more Windows applications being deployed by the Resource Extension. If the operating system installation on the OS VHD does not have the required set of roles or features enabled, then they are enabled prior to performing the other installation requirements.

The Windows Application Profile also contains the sections in the following table to install and configure the application. Details on each section are provided in the JSON reference.

Section	Description
Provisioning Scripts	Scripts that are run at different steps in the provisioning of the Virtual Machine Role.
SQL Profile	Describes instructions on specializing a SQL instance inside the virtual machine.
Web Deploy Applications	Web Deployment Packages to install.
SQL DAC Applications	SQL DAC applications to install.
Script Applications	Script applications to install.

The following JSON example shows the Windows Application Profile for a sample Resource Extension. In this example, a web site is being provisioned in IIS.

The Provisioning Scripts section defines the command script that is going to be run when the Virtual Machine Role is provisioned. The executable cmd.exe will be run with a command script called iisconfig.cmd. This script file must be included in the IISConfiguration.cr folder that was specified in the Application Payload section.

In this case, no SQL DAC applications or Web Deploy applications are required, so these sections are left blank.

The Windows Server Roles And Features section lists the set of Windows features and roles that are required by IIS and the web site being deployed. If any of these features or roles are not enabled in the OS VHD that is selected when the Virtual Machine Role is provisioned, then they are enabled prior to the provisioning script being run.

"WindowsApplicationProfile": {
    "ProvisioningScripts": [
        {
            "AlwaysReboot" : false,
            "ApplicationPayloadId" : "123dbce1-8ccd-4fb1-af39-a2a3b69b4123",
            "DeploymentOrder" : 1,
            "ErrorPolicy" : "FailOnMatch",
            "ExecutableAndParams" : {
                "Executable" : "cmd.exe",
                "Parameters" : "/q /c iisconfig.cmd [Param.IISPort]"
            },
            "ExitCodeRegex" : "[[1-9][[0-9]*",
            "RebootExitCodeRegex" : null,
            "RestartOnRetry" : false,
            "ScriptBlock" : null,
            "ScriptCredential" : null,
            "ScriptType" : "PreInstall",
            "StandardErrorPath" : "C:\\iisconfig-gceerr.txt",
            "StandardErrorRegex" : null,
            "StandardInput" : null,
            "StandardOutputPath" : "C:\\iisconfig-gceout.txt",
            "StandardOutputRegex" : null,
            "TimeoutInSeconds" : 1200,
            "WorkingDirectory" : null
        }
    ],
    "SQLDacApplications": [],
    "WebDeployApplications": [],
    "WindowsServerRolesAndFeatures": [
        "Web-Server",
        "Web-WebServer",
        "Web-Common-Http",
        "Web-Default-Doc",
        "Web-Dir-Browsing",
        "Web-Http-Errors",
        "Web-Static-Content",
        "Web-Http-Redirect",
        "Web-DAV-Publishing",
        "Web-Health",
        "Web-Http-Logging",
        "Web-Custom-Logging",
        "Web-Log-Libraries",
        "Web-ODBC-Logging",
        "Web-Request-Monitor",
        "Web-Http-Tracing",
        "Web-Performance",
        "Web-Stat-Compression",
        "Web-Dyn-Compression",
        "Web-Security",
        "Web-Filtering",
        "Web-Basic-Auth",
        "Web-CertProvider",
        "Web-Client-Auth",
        "Web-Digest-Auth",
        "Web-Cert-Auth",
        "Web-IP-Security",
        "Web-Url-Auth",
        "Web-Windows-Auth",
        "Web-App-Dev",
        "Web-Net-Ext",
        "Web-Net-Ext45",
        "Web-AppInit",
        "Web-ASP",
        "Web-Asp-Net",
        "Web-Asp-Net45",
        "Web-CGI",
        "Web-ISAPI-Ext",
        "Web-ISAPI-Filter",
        "Web-Includes",
        "Web-WebSockets",
        "Web-Ftp-Server",
        "Web-Ftp-Service",
        "Web-Ftp-Ext",
        "Web-WHC",
        "Web-Mgmt-Tools",
        "Web-Mgmt-Console",
        "Web-Mgmt-Compat",
        "Web-Metabase",
        "Web-Lgcy-Mgmt-Console",
        "Web-Lgcy-Scripting",
        "Web-WMI",
        "Web-Scripting-Tools",
        "Web-Mgmt-Service"
    ]
}

Share via