Set administrative metadata for Liberty resources

We can use the admin-metadata.xml file to set administrative metadata for server, cluster, application, and runtime resources. Administrative metadata associates information such as tags, owners, contacts, and notes with resources, making it easier to find information about resources in large topologies. For example, server metadata showing the owner of a server can assist finding the correct person to contact if the server requires changes. The admin-metadata.xml file uses XML format and does not exist by default. We must create the file and place it in a server configuration directory or in the Liberty (runtime) etc directory. After placing the admin-metadata.xml file in a supported directory, we can view the metadata in Admin Center or augment the metadata through application programming interfaces (APIs).

  1. Determine whether we want the admin-metadata.xml file to set metadata for a particular server or for all servers in the runtime environment.

      server An admin-metadata.xml file in a server configuration directory sets metadata for the server, its cluster, and its applications. The file path is...

      If the $WLP_USER_DIR variable is set in a server.env file or command window,

        $WLP_USER_DIR/servers/server_name/admin-metadata.xml.
      runtime An admin-metadata.xml file in the runtime etc directory sets metadata for runtime resources. The file is visible to all servers that use the runtime environment. The file path is...

        ${wlp.install.dir}/etc/admin-metadata.xml

      The etc directory does not exist by default; we must create the etc directory.

  2. Configure administrative metadata in the admin-metadata.xml file.

    1. Create a text file named admin-metadata.xml in the location determined in step 1. If the file already exists, open an editor on the file.

    2. In an editor, specify administrative metadata for any of the following resource objects:

      • <server> - Set no more than one server metadata.
      • <cluster> - Set no more than one cluster metadata.
      • <application> - Set any number of application metadata.
      • <runtime> - Set no more than one runtime metadata.

      Restriction: We cannot set host metadata in an admin-metadata.xml file. We must manage host metadata using Admin Center or AdminMetadataManager MBean APIs or scripts.

      For each resource object, specify up to four types of metadata:

        tag Assign zero or more tags to a resource object. We use a tag to search for resources.
        owner Assign no more than one owner to a resource object. An owner is typically a person or entity responsible for the metadata. The owner can provide a key for the metadata.
        contact Assign zero or more contacts to a resource object. A contact is a person or entity who can provide information about the resource object.
        note Assign no more than one note to a resource object. A note is arbitrary text.

      For guidance on file contents, see:

      Tags that contain uppercase characters are converted to lowercase before deployment to the collective repository. Thus, <tag>MyTag</tag> in an admin-metadata.xml file displays as mytag in Admin Center.

    3. Save the file changes.

Server metadata in the server configuration directory is deployed to, or undeployed from, the collective repository when the following events occur:

  • The server joins to the collective controller through the collective join command
  • The controller or member server starts
  • A member is removed from the collective controller through the collective remove command
  • The admin-metadata.xml file changes

The product monitors the admin-metadata.xml file after the server starts and dynamically updates server metadata in the collective repository to reflect any file changes.

Important: Ensure the server is running when you delete an admin-metadata.xml file. If an admin-metadata.xml file is deleted while the server is running then the product removes the metadata from the repository. If some elements are deleted from the file when the server is stopped, the product removes those elements from the repository when the server starts. However, if the admin-metadata.xml file is deleted while the server is stopped, the metadata will not be removed from the repository when the server starts.

Cluster metadata is deployed to, or undeployed from, the collective repository when the following events occur:

  • A cluster member connects with the controller, such as when a cluster member starts.
  • The admin-metadata.xml file changes for a cluster member
  • The last cluster member is removed, such as when the last cluster member stops

Application metadata is deployed to the collective repository when the following events occur:

  • An application is installed on a server or cluster
  • The admin-metadata.xml file changes for an application

Runtime metadata is deployed to, or undeployed from, the collective repository when the following events occur:

  • A server joins the collective controller through the collective join command
  • The runtime installation directory (${wlp.install.dir}) is unregistered, resulting in undeployment
  • No dynamic updating through the file monitor or AdminMetadataManager MBean

The product does not monitor the admin-metadata.xml file in the etc directory. We must restart the server to update the runtime metadata in the collective repository.

Note: Changes made to metadata in the repository using Admin Center are not removed unless the resource is completely removed from the collective.


Example admin-metadata.xml files

Show admin-metadata.xml files for server and runtime metadata:

Example: admin-metadata.xml in a server configuration directory

    <admin-metadata>
    
    <server owner="John Doe">
        <tag>servertag1</tag>
        <tag>servertag2</tag>
        <tag>servertag3</tag>
        <contact>Mike</contact>
        <contact>Fred</contact>
        <contact>Susan</contact>
        <note>This server is the best server.</note>
    </server>
	
    <cluster name="cluster1" owner="Tom Wood">
        <tag>clustertag1</tag>
        <tag>clustertag2</tag>
        <tag>clustertag3</tag>
        <contact>Roger</contact>
        <contact>Steve</contact>
        <contact>David</contact>
        <note>This cluster is the best cluster.</note>
    </cluster>
	
    <application name="app1" owner="Sam Hardison">
        <tag>app1tag1</tag>
        <tag>app1tag2</tag>
        <tag>app1tag3</tag>
        <contact>Jack</contact>
        <contact>Tom</contact>
        <contact>Michael</contact>
        <note>Liberty 8.5.5.x with IBM JDK</note>
    </application>	
	
    <application name="app2" owner="Michael Dell">
        <tag>app2tag1</tag>
        <tag>app2tag2</tag>
        <tag>app2tag3</tag>
        <contact>Susan</contact>
        <contact>Roger</contact>
        <contact>Fred</contact>
        <note>Liberty 8.5.5.x with IBM JDK</note>
    </application>

</admin-metadata>

Example: admin-metadata.xml in the runtime etc directory

    <admin-metadata>
	
    <runtime owner="Admin Boss">
        <tag>runtimetag1</tag>
        <tag>runtimetag2</tag>
        <tag>runtimetag3</tag> 
        <contact>Steven</contact> 
        <note>Liberty 8.5.5.x with IBM JDK</note> 
    </runtime>

</admin-metadata>


What to do next

We can view administrative metadata in Admin Center. For example, suppose a collective controller named controller1 has the following admin-metadata.xml file in its server configuration directory

    $WLP_USER_DIR/servers/controller1 

    <admin-metadata>
    <server owner="John Doe">
        <tag>controller</tag>
        <tag>replica_controller</tag>
        <contact>Michal</contact>
        <contact>Felix</contact>
        <contact>Travis</contact>
        <contact>Philippa</contact>
        <contact>Amy</contact>
        <note>The first of three replica controllers. At least three replica controllers are needed for high availability.</note>
    </server>
</admin-metadata>

When the controller has <feature>adminCenter-1.0</feature> in its <featureManager> configuration, the Admin Center Explore tool displays the metadata in details about the controller1 server:

For information about viewing administrative metadata in the Explore tool, see Set and view administrative metadata in Admin Center.

Also, we can use methods in AdminMetadataManagerMBean to add, retrieve and set application metadata in the collective repository, as well as remove it from the collective repository.