Table Of Contents
Programmatic Management Interface
Project Management
AON Version 2.4 introduces the concept of projects to partition the work performed by different development teams. A project contains all of the resources, such as policy execution plans (PEPs), message types, and property sets, created by a team. Nodes and other global resources are shared among multiple projects, yet changes to those resources within a given project do not affect other projects. A single node can simultaneously process message traffic for multiple projects.
AON users are assigned permissions to access AON resources based on the roles assigned to them when they are created in AMC. Some users may be given permission to modify any resource or entity in the AON environment, while others may be limited to modifying a subset of resources contained in the project to which they are assigned.
AON now supports the concept of multi-tier environments, in which projects can be developed and thoroughly tested before being deployed to a production environment. Development nodes are managed by one AMC, while production nodes are managed by a different AMC. Projects are exported from the development tier and imported into the production tier.
This AON release also includes the Programmatic Management Interface (PMI) feature, which provides a scriptable interface to AMC. PMI enables users to develop custom applications that can be used to automate the task of deploying changes to AON nodes.
This chapter includes the following topics:
•Programmatic Management Interface
Projects
Projects are the containers that hold all of the resources, including nodes, PEPs, message types, and other resources, that are assigned to a development team. A team working in a project is isolated from all other projects. Users can create and deploy resources to the AON network without regard for what other teams are doing with their own projects. Those changes, once deployed, have no bearing on how nodes used by other projects process messages for those projects.
Note When you log on to AMC, you must open a project before you can view the following items:
•Properties tab
•Deploy tab
•Monitor tab
•Licensing and Extensions on the Admin tab
These items are hidden until you open a project.
AMC maintains deployment requests (DR) for each project. A project has a DR for each node associated with that project. A project also has a global DR whose scope is all of the nodes associated with that project. Each PEP, property set, or message type created in a project is either bound to a single node or bound globally across all nodes in the project. When a global project resource is changed, it causes the resource to be deployed to all nodes associated with the project.
System Project
The system project contains resources that are shared by all application projects. For example, a property set created in a system project by a system administrator can be referenced by PEPs belonging to multiple projects. A user assigned to the system project, assuming the user has appropriate role-based permissions, can create and edit shared resources in the system project. It is also the responsibility of the system administrator to deploy shared resources to the appropriate nodes. These shared resources can be viewed and referenced by other projects as read-only resources.
Note PEPs and Message Types are not allowed in the System project. You cannot access the System project from ADS.
Project Resources
Since nodes are shared among projects, the resources configured on a node must not conflict with resources from other projects. When you create a new project, you also specify a prefix to be associated with that project. AMC then appends the project prefix to resources that are created by the project. This ensures that each resource has a unique name across different projects.
Resources in a project are either assigned to a particular node, or they have a global scope, meaning they are deployed to every node that is assigned to the project. Resources that are created within a project are bound to that project and are not accessible from any other project.
A newly installed AMC creates predefined resources in the system project. The predefined resources include:
•Adapters (aonp, http, jms, pmode)
•Property sets (see Table 1-1)
Extensions
Extensions are uploaded into and deployed from a particular project. Any property set categories included in the extension are accessible only to the project that uploaded the extension. Each project must upload its own unique extensions. An extension uploaded by an application project cannot be shared among other projects. However, extensions uploaded into the system project can be shared.
Extensions are subject to the following limitations:
•Adapters and adapter extensions are only supported in the project-global scope of the system project. They cannot be uploaded from a user project.
•Schemas, transforms, transform parsers, and JMS bindings are only supported in the project-global scope of a project.
•There can be only one instance of an extension package in AMC. If two different projects attempt to upload the same extension, the second upload attempt fails.
Upgrading from a Previous AON Release
If you upgrade a previous release to AON 2.4, the AMC installer creates an additional project. The default name is "USER_PROJECT," however, you can specify a different name during the upgrade process. This project contains all PEPs and message types that were configured in AMC before the upgrade. All nodes and users that were configured in AMC before the upgrade are also assigned to this project. PEPs and message types in this project have a prefix, called "PREFIX" by default but can be set to something else during the upgrade process. Users configured in AMC before upgrade will have the same permission in this version of AMC.
Note that adapter and adapter extension packages can only be associated with system project, these resources will be assigned to system project after upgrade.
The sections that follow describe various aspects of working with projects, including:
Creating a New Project
How to Get There
Go to Project, then click the New button. Complete the following fields:
•Project name—The project name must start with an alphanumeric character and may contain only letters, numbers, hyphens, and underscores. If you insert spaces in your project name, AMC removes them.
•Project prefix—The project prefix is appended to the names of resources created by that project. It is used to identify the project that created a given resource.
•Project description
After you click the Next button, subsequent pages provide you the opportunity to assign nodes and users to the project.
See the following additional topics:
Viewing a Project
How to Get There
Go to Project, then select a project and click the View button
The Project Details page displays the basic details of the selected project, including:
•Project name
•Project prefix—the prefix is used to identify resources assigned to that project.
•Project description
•Assigned nodes—nodes for which project members are able to create PEPs, message types, and other resources.
•Assigned users—users that have permission to modify project resources.
Opening a Project
How to Get There
Go to Project, then select a project and click the Open button. Doing so loads the Project Details page. From there you can click any of AMC's tabs to begin configuring the project.
Editing a Project
How to Get There
Go to Project, then select a project and click the Edit button. Doing so enables you to change the project description. You cannot change the project name or prefix.
Assigning Users to a Project
How to Get There
Go to Project, then select a project and click the Assign Users button.
To assign users, do the following:
1. Select a user from the Available Users column. Control+click to select multiple users.
2. Click the right arrow button to move the users to the Assigned Users column.
3. If necessary, select users from the Assigned Users column and use the left arrow button to remove them from the project.
4. You can also double-click a user to immediately move it from one column to the other.
5. Click the Save button to save your changes.
Users must be assigned to a project before they can modify it, and only assigned users can manipulate resources in that project. External users cannot be assigned to projects. A user can be assigned to more than one project, however, that user can access only one project at a time. Users with security, network, and system administrator roles are not shown, as they are assigned to all projects by default.
Additionally, users with the following roles are assigned to every project by default:
•System administrator
•Security administrator
•Network administrator
For additional information about users and role-based access control, see the "Managing Local Users" section.
Assigning Nodes to a Project
How to Get There
Go to Project, then select a project and click the Assign Nodes button.
To assign users, do the following:
1. Select a user from the Available Nodes column. Control+click to select multiple nodes.
2. Click the right arrow button to move the users to the Assigned Nodes column.
3. If necessary, select nodes from the Assigned Nodes column and use the left arrow button to remove them from the project.
4. You can also double-click a node to immediately move it from one column to the other.
5. Click the Save button to save your changes.
Deleting a Project
How to Get There
Go to Project, then select a project and click the Delete button.
Depending on whether the project has resources assigned or has been opened by other users, the following occurs:
•If resources have been configured, AMC asks to confirm the deletion. If you continue, deployment requests are generated. You must deploy these changes to the nodes in order to completely delete the project resources from the AON environment. After the deletion has been deployed, return to the Project List to delete the project
•If users have opened the project, you are asked to confirm the deletion. If you continue, the project is immediately deleted.
•If there are no project resources and no users have opened the project, the project is immediately deleted.
Role-Based Access Control
AON Version 2.4 introduces two new user types and modifies the capabilities of the four existing user types. The two new user types include:
•System administrator—a user that is able work with all resources. This user has no restrictions in the management of AMC, ADS, and nodes.
•Application developer—a user that is able to work only with resources contained in assigned projects.
The existing user types are modified as follows:
•Network administrator—a user that is able to work with network resources. This user can also open and view projects.
•Security administrator—a user that is able to work with security-related resources. This user can also open and view projects.
•Application administrator—a user that is able to create project, create users, and assign users to projects. This user can also manage project-related resources.
•Application designer—a user that is able to upload and register extensions. This user can also open and view projects.
For more information about user types, including the specific AMC pages each user can view and modify, see the "Managing AON Users" section.
Multiple AON Environments
AMC supports the use of multiple AON environments in the lifecycle of a project. For example, development, staging, and production activities can be carried out in three separate AON environments. Project teams can develop and test AON projects in the development tier. They can then request that their projects be promoted, first to the staging tier, then to the production tier.
It is assumed that AON nodes in each tier are managed by different AMC installations. For example, nodes used to test new PEPs in the development tier are not expected to process production traffic.
Promotion of AON resources from one tier to another is accomplished using the following steps:
1. The AMC of the source tier exports all of the resources for a project. The export operation creates a configuration archive. For more information, see Exporting Projects.
2. The archive is modified to adjust any environment-dependent parameters that differ between the source and destination tiers. You can create scripts to automate this task. For more information, see Archive File.
3. The configuration archive is imported into the same project in the AMC of the destination tier. For more information, see Importing Projects.
4. The imported resources are deployed to the nodes of the destination tier.
The export, import, and deploy operations are available through a programmatic interface to support control of promotion from a workflow automation tool. For more information, see Programmatic Management Interface.
Assumptions
This feature is subject to the following assumptions:
•Project resources created for a for a node can only be promoted to nodes running the same version of AON software and running on the same hardware.
•Version control of projects is accomplished by the user using an external version control system. Exported configuration archives, created by AMC, must be versioned and managed by the user.
•Rollback is accomplished by importing an earlier version of a project's configuration archive.
•Shared resources must be deployed before dependent project resources can be deployed.
•The name and prefix assigned to a project cannot be changed after project creation. The same prefix must be used in all tiers to which the project may be promoted.
•To prevent message type conflicts, it is assumed that each application team will apply distinct URI patterns in the message types they create.
•Message type ordering is required only at the Project Level (not needed between Projects due to URI namespace uniqueness).
This feature is subject to the following limitations:
•Project-level log and trace viewing is not supported in this release.
•Deployment request history will not be migrated from previous software releases during the AMC upgrade. Only the latest version of each resource will be migrated.
Exporting Projects
How to Get There
Go to Admin > Data Migration.
The Export Project page contains the following elements:
Archive File
When you export a project, AMC writes a zip file containing configuration data. This configuration archive contains all of the data related to the project. You can then edit the information contained in the archive to modify the configuration data that must change in order for the project to function in the new AMC environment.
The file structure of the configuration archive and schemas for individual data files are listed in the sections that follow. You can use this information to modify configuration files as appropriate for your environment. You can also develop custom scripts to automate this task.
Note Cisco reserves the right to modify archive schemas as AON evolves. Schemas are not guaranteed to be backward compatible. Thus custom scripts may need to be adjusted from one release to the next.
For the complete archive file structure and schema, see the "Archive Schema" section.
Importing Projects
Before importing a project, you must prepare a node mapping file. This file maps the configuration for each node in the source AMC to any combination of nodes in the new AMC environment.
The example below shows a sample node mapping file. In this example, sourceNode1 is mapped to a single node on the destination AMC. The configuration for sourceNode2 is mapped to two nodes in the destination AMC. The configuration for sourceNode3 is not needed in the destination AMC, so it is not mapped to a node.
<PromotionNodeMap><SourceNode name="sourceNode1"><DestinationNode name="destinationNode1"/></SourceNode><SourceNode name="sourceNode2"><DestinationNode name="destinationNode1"/><DestinationNode name="destinationNode2"/></SourceNode><SourceNode name="sourceNode3"/></PromotionNodeMap>
Note To mimic the import behavior of previous AON releases, map only a single node in the source AMC to a single node in the destination AMC.
Create a node mapping file and store it in a location where AMC has read access.
How to Get There
Go to Admin > Data Migration > Import.
The Import Configuration page contains the following elements:
The Configuration Information page contains the following elements:
After you click the Import button, the subsequent page reports either success or failure of the import operation, along with error, warning, or informational messages, if any.
Programmatic Management Interface
The programmatic management interface feature (PMI) provides an interface so that third-party applications can manipulate data in AMC. Using the appropriate APIs, you can configure an application to:
•Log in to AMC.
•Display a list of projects.
•Export projects
•Import projects
•Display a list of deployment requests (DRs)
•Deploy to nodes
•Export a list of users and their permissions
•Import a list of users and their permissions
Any client that uses these APIs to interact with AMC, must adhere to the following restrictions:
•The client must use HTTPS to connect to AMC.
•The client must have a server certificate in the AMC trust store to properly authenticate.
•The client must use the "aonsadmin" user ID to log into AMC.
•All web service calls must be RPC based.
•SOAP version 1.1 is supported. Version 1.2 is not supported.
•All error messages are handled as SOAPFault. The client is expected to process SOAPFaults appropriately.
Sample Promotion Workflow
Using the schemas and APIs documented in "AON Schemas," a custom application might promote resources from one AMC to another as follows:
1. The client application invokes Login API to gain access to AMC. It then invokes the Export API. AMC gathers up all of the golden resources belonging to the project, and exports them in a configuration archive.
2. The client invokes a script that opens the configuration archive and modifies environment-dependent parameters in various resources. When the changes are complete, the modified configuration archive is written back to disk.
3. The client tool logs into the staging AMC and calls the Import API. This operation reads the configuration archive and replaces all existing resources of a specified project in the staging tier with the contents of the archive. The staging AMC calculates all of the add, modify, and delete changes needed in each AON node to accomplish the replacement. These changes are placed in the project's global and node deployment requests.
4. The client invokes the Deploy API of the staging AMC. This pushes all of the project's deployment requests to the appropriate nodes.
For a complete list of APIs and information on the sample PMI client included with AMC 2.4, see the "Programmatic Management Interface APIs" section.