Chapter 4 Plans

A plan is used to perform operations on hosts that are managed by the provisioning system.

This chapter covers the following topics:

• Managing Plans

• Creating Plans

• Running Plans

• Summary of Plan CLI Commands

Managing Plans

You can use the Sun N1 Service Provisioning System software browser interface to manage plans. The following pages in the browser interface include information about how to view and manage plans:

• Plans page. List plans and add new plans to the list. You can also access other plan pages to view plan details.

  To see which plans are already checked in, choose Plans from the navigation menu.

• Details page. View detailed information about the plan, such as its attributes and values. This page also provides information and buttons that enable you to manage the plan.

  • To see details about a plan, go to the Plans page, click the name of the plan you want, and view details on the Details page.

  • To delete a plan, go to the plan's Details page and click Delete. Click Continue To Delete, or click Cancel if you do not want to delete the plan.

    ---

    Note –

    You do not need to delete generated plans or direct-run component procedures. These plans are removed automatically from the system when the component from which they were generated is deleted.

    ---

  • To move a plan to another folder, go to the plan's Details page and click Move. Specify the name of the folder in which to move the plan and click Move, or click Cancel if you do not want to move the plan.

    ---

    Note –

    If you plan to move a plan into a folder that does not yet exist, click New Folder in the Move Component window. This new folder inherits the permissions from its parent folder. After you click Create, the folder tree displays with the new folder selected. Click Move.

    ---

• Advanced Edit page. Change what a plan does by changing the plan's XML.

  To edit a plan, see How to Edit a Plan.

In addition to managing plans, you can create plans and run plans as described later in this chapter.

You can also use the CLI to work with plans. See Summary of Plan CLI Commands. For detailed information about the CLI commands, see the Sun N1 Service Provisioning System 5.1 Command-Line Interface Reference Manual.

How to Edit a Plan

Steps

1. Go to the Details page of the plan you want, and click Advanced Edit.

2. Modify the XML or import new XML for the plan.

   To import a plan from another system, do one of the following:

   • Type the full path of the file, then click Replace.

   • Click Browse and locate the file, then click Replace.

3. Check in the plan.

   • Click Check In to save the plan with the same name.

     The Plans page appears.

   • Click Check In As to save the plan with a different name.

     A new page appears that tells you that you are about to check in a plan. The version number increments.

4. Click Continue To Check In.

Creating Plans

You can create an generated plan, create a custom plan, or customize a generated plan.

The provisioning system can generate automatically a plan that consists of more than one direct-run component procedures. You can run this plan directly or save it for use as a template for more complex plans that you author in XML.

For deployments that involve the coordination of multiple components, multiple host sets, or both, write a plan and use the provisioning system XML schema to define operations. Such operations might include dependency checks and scripting that execute commands on an application console. Once the plan is written, you need to check it in to the plan repository.

How to Create Generated Plans

You create an generated plan from a component's Details page.

Before You Begin

To create a generated plan, you must belong to a user group that has Create, Edit, and Delete permission on the folder that contains the component for which you want to generate a plan.

Steps

1. From the navigation menu, choose Components.

   The Components page lists the components that are already checked in.

2. If necessary, change folders so that you can view the component that you plan to deploy.

   1. Click Change Folder.

   2. Specify the name of the folder that contains the component, and click Change to Selected Folder.

      The Components page now lists the components in the specified folder.

3. In the table listing components, find the row describing the component you would like to deploy, and click Details.

   The component's Details page displays.

4. In the Component Procedures table, select each procedure to include in the plan.

5. In the bottom row of the Component Procedures table, click Generate Plan With Checked Procedures.

   The generated plan's Advanced Edit page appears.

6. In the Plan field, type the new plan's name.

7. Click Check In.

   ---

   Note –

   You might see this message: Warning - plan names and/or paths differ. This message indicates that you specified a plan name that is different from the plan name specified in the XML model. The XML model is updated according to what you type in the plan name field.

   ---

8. Confirm the component check-in.

   1. Verify that you specified the correct plan name.

   2. If necessary, select the component's new version number.

   3. Click Continue to Check In.

   The new plan's Details page appears.

How to Create a Custom Plan

You can create a plan by using a schema-validating editor, such as TurboXML, or on the Advanced Edit page of the browser interface.

This procedure describes how to import a plan that you have written by using an XML editor.

Steps

1. Write a plan.

   See the XML schema elements described in Chapter 2, Shared Schema Used by Components and Simple Plans, in Sun N1 Service Provisioning System 5.1 XML Schema Reference Guide and Chapter 4, Plan Schema, in Sun N1 Service Provisioning System 5.1 XML Schema Reference Guide.

2. Launch the browser interface and go to the Plans page.

3. (Optional) Click Change Folder and specify the folder that will contain the new plan.

   A window appears where you specify the name of the folder in which to create the component.

   • If the folder exists, select the name of the folder, and click Change to Selected Folder.

     The Plans page displays the list of plans in the specified folder.

   • If the folder does not exist, create the folder.

     1. Specify the parent folder, and click New Folder.

        The Create New Folder window appears.

     2. Type the name of the new folder, and click Create.

        The new folder inherits its permissions from its parent folder. After you click Create, the folder tree displays with the new folder selected.

        ---

        Note –

        You cannot create multiple folder levels at one time. To create several nested folders, you must return to the Change Folder window and repeat steps A and B.

        ---

     3. After the folder is created, select the name of the folder, and click Change to Selected Folder.

        The Plans page displays showing the list of plans in the specified folder.

4. Type the name and brief description for the plan that you want to create, and click Create.

   The Advanced Edit page for the plan appears.

   The provisioning system creates an XML skeleton for the plan.

5. In the Plan Definition field, do the following:

   • Enter the XML for the plan.

   • To import a plan that is stored on your local system, type the full path name of the file or click the Browse button. Then, click Replace.

6. Click Check In.

   A window appears that tells you that you are about to check in a plan. The plan is assigned Version 1.0.

7. Click Continue To Check In.

Running Plans

A plan must be checked in to the plan repository before it can be run. When you run a plan, it performs operations on the hosts that you specify.

A preflight is the simulated execution of a plan to a simulated UNIX® environment that finds and reports any errors or potential errors that might affect the deployment. A preflight always precedes a deployment, but you can run a preflight as a standalone operation.

You can also run a detailed preflight, which performs the following functions:

• Checks the availability and the connectivity of target hosts

• Confirms permissions

• Validates dependencies

How to Run a Plan

Use this procedure to run a plan from a plan's Details page in the browser interface.

Before You Begin

Ensure that you have the installation information that you need to be able to set the plan's variable settings.

To run a plan, you must belong to a user group that has Allow on Host Set permissions on the folder that contains the plan you want to run.

Steps

1. Go to the plan's Details page, and click Run.

   The plan's Run page appears.

2. In the Plan Parameters area, select the variable settings for the component you want to deploy.

   • If the variable settings have been established for this component, choose the appropriate settings from the menu.

   • If the settings are not available from the menu, click Select From List.

     The Select Variable Settings From List window appears.

     • If you want to use another component's variable settings, click Import Set.

       The Import Variable Settings window appears.

       1. If necessary, go to the folder that contains the component with the variable settings you want to import.

       2. Select the component version.

          ---

          Note –

          Variable settings can vary between component versions.

          ---

       3. Click Import Variable Settings.

          The imported variable settings appear in the table.

       4. Click Select.

     • If you want to create new variable settings, click Create Set.

       The Select Variable Settings From List window appears.

       1. In the text field at the top of the table, type a name to use for the new variable settings.

       2. Select the component variable you want to change.

          The table cell is highlighted and a text field appears.

       3. Type a new value for the component variable.

       4. (Optional) Repeat the previous substeps b and c for each variable value you want to change.

       5. After updating the variable settings values, click Save.

          The new variable settings appear in the table.

       6. Click Select.

3. Specify where to deploy the component.

   • To specify a host, type the host name in the Target Host field, or click Select From List and select a host.

   • To select a target host set, choose one from the Target Host Set menu.

4. In the Plan Variables area, configure the variables you want to set.

   Whether there are variables to configure depends on the contents of the plan.

5. In the Options area, specify whether to perform a detailed preflight.

   The detailed preflight attempts to simulate every step of the plan that will run on the remote agent. The detailed preflight tests the following functions:

   • Resource installation

   • <execNative> calls

   • File transformations

   • File deletion, when uninstalling resources

   Running a detailed preflight increases the amount of time the preflight takes.

6. (Optional) To limit the number of hosts running at the same time, type the number of hosts on which to run a plan in the field provided.

   When a plan is run on several hosts simultaneously, all hosts must complete a particular step before any host can begin the next step. If the number of hosts is too high, the network connection can time out between steps.

   For example, the time interval between Host A finishing the first step and being able to run the second step might be too long. In this case, the length of the time interval causes the network connection to time out.

7. (Optional) To limit the overall running time of a plan or of native calls, type a number in the fields provided, then choose the time unit, such as minutes, from the menu.

   By limiting the runtime of a plan or native call, you prevent a nonresponsive host from tying up the progress of a running plan.

   If you set up a notification rule to alert you to plan failures, when the plan times out, you will be notified that the plan was unsuccessful.

   For information about setting up notification rules, see Configuring Email Notification in Sun N1 Service Provisioning System 5.1 System Administration Guide.

8. Specify whether to deploy the component.

   • To run just the preflight test of the procedure, click Run Preflight Only.

   • To run the preflight test and then the procedure itself, click Run Plan (Includes Preflight).

     Note that the procedure is not run if the preflight fails.

How to Deploy a Component by Using a Direct-Run Component Procedure

Most components include install, uninstall, and snapshot procedures. A component might also include control procedures that manage the installed component. For example, a control procedure might to start or stop the application.

You might be able to use one of the direct-run component procedures that the provisioning system automatically generated when you checked in your component. Use this method for straightforward deployments that do not involve more than one component or synchronization between hosts.

Steps

1. From the navigation menu, choose Components.

   The Components page lists the components that are already checked in.

2. If necessary, change folders so that you can view the component that you plan to deploy.

   1. Click Change Folder.

   2. Specify the name of the folder that contains the component, and click Change to Selected Folder.

      The Components page now lists the components in the specified folder.

3. Click the name of the component that you want.

   The Details page for that component appears.

4. In the Component Procedures table, determine which procedure to run, and click Run.

   The provisioning system generates a plan, which is stored in the /system/autogen folder.

   The Run page for the generated plan appears.

5. In the Plan Parameters area, select the variable settings for the component you want to deploy.

   • If the variable settings have been established for this component, choose the appropriate settings from the menu.

   • If the settings are not available from the menu, click Select From List.

     The Select Variable Settings From List window appears.

     • If you want to use another component's variable settings, click Import Set.

       The Import Variable Settings window appears.

       1. If necessary, go to the folder that contains the component with the variable settings you want to import.

       2. Select the component version.

          ---

          Note –

          Variable settings can vary between component versions.

          ---

       3. Click Import Variable Settings.

          The imported variable settings appear in the table.

       4. Click Select.

     • If you want to create new variable settings, click Create Set.

       The Select Variable Settings From List window appears.

       1. In the text field at the top of the table, type a name to use for the new variable settings.

       2. Select the component variable you want to change.

          The table cell is highlighted and a text field appears.

       3. Type a new value for the component variable.

       4. (Optional) Repeat the previous substeps b and c for each variable value you want to change.

       5. After updating the variable settings values, click Save.

          The new variable settings appear in the table.

       6. Click Select.

6. Specify where to deploy the component.

   • To select a host, type the host name in the Target Host field or click Select From List and select a host.

   • To select a target host set, choose one from the Target Host Set menu.

7. In the Plan Variables area, configure the variables you want to set.

   Whether there are variables to configure depends on the contents of the component procedure you select.

8. In the Options area, select whether to perform a detailed preflight.

   The detailed preflight attempts to simulate every step of the plan that will run on the remote agent. The detailed preflight tests the following functions.

   • Resource installation

   • <execNative> calls

   • File transformations

   • File deletion, when uninstalling resources

   Running a detailed preflight increases the amount of time the preflight takes.

9. (Optional) To limit the number of hosts running at the same time, type the number of hosts on which to run a plan in the field provided.

   When a plan is run on several hosts simultaneously, all hosts must complete a particular step before any host can begin the next step. If the number of hosts is too high, the network connection can time out between steps.

   For example, the time interval between Host A finishing the first step and being able to run the second step might be too long. In this case, the length of the time interval causes the network connection to time out.

10. (Optional) To limit the overall running time of a plan or of native calls, type a number in the fields provided, then choose the time unit, such as minutes, from the menu.

    By limiting the runtime of a plan or native call, you prevent a nonresponsive host from tying up the progress of a running plan.

    If you set up a notification rule to alert you to plan failures, when the plan times out, you will be notified that the plan was unsuccessful.

    For information about setting up notification rules, see Configuring Email Notification in Sun N1 Service Provisioning System 5.1 System Administration Guide.

11. Specify whether to deploy the component.

    • To run just the preflight test of the procedure, click Run Preflight Only.

    • To run the preflight test and then the procedure itself, click Run Plan (Includes Preflight).

      Note that the procedure is not run if the preflight fails.

Summary of Plan CLI Commands

You can use the following pdb commands to manage plans:

• pdb.p.ci – Checks in a new version of a plan

• pdb.p.co – Checks out a plan in XML format

• pdb.p.del – Deletes a plan

• pdb.p.genplan – Generates and displays output for a plan in XML format

• pdb.p.la – Lists all versions of all plans

• pdb.p.lo – Shows detailed information about a plan

• pdb.p.lv – Lists all versions of a plan

• pdb.p.sc – Associates a plan with a set of categories

• pdb.p.sh – Shows or hides a plan

The following pe commands are associated with running plans:

• pe.h.prep – Prepares a set of hosts

• pe.p.del – Deletes the history of a completed plan run

• pe.p.en – Displays the output of an <execNative> step

• pe.p.la – Lists running and completed plans

• pe.p.lo – Lists detailed information about a running or completed plan

• pe.p.lp – Lists the subplans and targets that are associated with a plan

• pe.p.run – Runs a plan

• pe.p.stop – Stops a plan that is running

• pe.pi.lo – Lists the parameters that are used to run a plan

For more information about the provisioning system CLI commands, see the Sun N1 Service Provisioning System 5.1 Command-Line Interface Reference Manual.