Setting administrative metadata for Liberty resources

You can use the admin-metadata.xml file to set administrative metadata for server, cluster, application, and runtime resources. Administrative metadata enables you to associate information such as tags, owners, contacts, and notes with resources. The metadata can simplify resource management and make it easier to find information about resources in large topologies. For example, server metadata that shows the owner of a server can assist you in more quickly 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. You 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, you can view the metadata in Admin Center or augment the metadata through application programming interfaces (APIs).

1. Determine whether you 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 ${wlp.install.dir}/usr/servers/server_name/admin-metadata.xml or, 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; you 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: You cannot set host metadata in an admin-metadata.xml file. You 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. You 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 Example: admin-metadata.xml in a server configuration directory and Example: admin-metadata.xml in the runtime etc directory.

      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.

<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>	

<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

You 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 Setting and viewing administrative metadata in Admin Center.

Also, you 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.