Overview Ambari's Kerberos Descriptor is JSON-formatted document used to help Ambari enable Kerberos for installed services. The descriptor contains the information needed to create the required principals and keytab files. It also declares configuration changes needed by the serviced so they a are configured for Kerberos properly. The Kerberos Descriptor is comprised of the compiled Kerberos descriptors found in the relevant service definitions with user-specified changes applied to it. This combination of data is known as the "Composite Kerberos Descriptor", where the separate parts are known as the "Stack-level Kerberos Descriptor" and the "User-specified Kerberos Descriptor". Each of these descriptors may be obtained from Ambari via is REST API: GET /api/v1/clusters/{CLUSER_NAME}/kerberos_descriptors/COMPOSITE GET /api/v1/clusters/{CLUSER_NAME}/kerberos_descriptors/STACK GET /api/v1/clusters/{CLUSER_NAME}/kerberos_descriptors/USER NOTE: Be sure to replace {CLUSTER_NAME} when the name of the relevant cluster. These REST API calls are for informational purposes only and therefore are read-only. Also, this data is available whether Kerberos is enabled or not. However the User-specified Kerberos Descriptor will most-likely be empty. The Kerberos Descriptor was designed to favor user-supplied change over the stack-level defaults; while maintaining forward compatibility in the even the stack-definitions change by adding new or updating existing component definitions. Because of this, it is expected that the User-specified Kerberos Descriptor is sparse, containing only the changes needed to be applied on top of the stack-level defaults. However as of Ambari 2.4.2, when enabling Kerberos via Ambari's Enable Kerberos Wizard, the complete Kerberos Descriptor is stored as the User-Defined Kerberos Descriptor. Storing the entire Kerberos Descriptor as the User-Defined Kerberos Descriptor is not necessarily a problem since the Composite Kerberos Descriptor will still be valid; and any additions to the Stack-level Kerberos Descriptor will be realized after Ambari server or stack upgrades. Unfortunately, issues can occur when changes to existing pieces of the Stack-level Kerberos Descriptor are encountered durning an upgrade. This is due to ambiguities encountered when upgrading the User-Specified Kerberos descriptor. If an issue with User-Defined Kerberos Descriptor is encountered, it may be necessary to manually edit it. This can be done by Getting the descriptor using Ambari's REST API Editing the descriptor using a text editor Putting the updated descriptor using Ambari's REST API Getting the descriptor using Ambari's REST API To get the User-Specified Kerberos Descriptor, the following REST API call may be issued to Ambari: GET /api/v1/clusters/{CLUSTER_NAME}/artifacts/kerberos_descriptor NOTE: Be sure to replace {CLUSTER_NAME} when the name of the relevant cluster. Notice that the API call access the "artifacts" resource of the cluster rather than "kerberos_descriptors" resource of the cluster. This is due to the storage implementation of the User-Specified Kerberos Descriptor data. If User-Specified Kerberos Descriptor was set, the response will look something like {
"href" : "http://host1.example.com:8080/api/v1/clusters/c1/artifacts/kerberos_descriptor",
"Artifacts" : {
"artifact_name" : "kerberos_descriptor",
"cluster_name" : "c1"
},
"artifact_data" : {
...
}
} The user-specified data will exist under the "artifact_data" section, which was removed to brevity. This API call can be issued using a command-line tool like curl and the output can be stored to a local file. For example: curl -u admin:admin -X GET -o kerberos_descriptor.json http://localhost:8080/api/v1/clusters/c1/artifacts/kerberos_descriptor NOTE: The user credentials ("-u admin:admin") and cluster name ("c1") should be changed for the particular cluster. After the call completes, the User-specified Kerberos Descriptor (with some additional metadata) will be in the file named kerberos_descriptor.json in the local directory.
Editing the descriptor using a text editor Once the User-specified Kerberos Descriptor has been obtained and stored in a local file, it may be edited using a text editor. Other than any fixes (additions, subtractions, etc...), the following lines in the file must be removed: "href" : "http://host1.example.com:8080/api/v1/clusters/c1/artifacts/kerberos_descriptor",
"Artifacts" : {
"artifact_name" : "kerberos_descriptor",
"cluster_name" : "c1"
}, This is metadata that will cause a failure when attempting to store the updated User-specified Kerberos Descriptor. The resulting JSON document should be something like {
"artifact_data" : {
...
}
} The user-specified data will exist under the "artifact_data" section, which was removed to brevity. After all needed changes are made, be sure to save the file.
Putting the updated descriptor using Ambari's REST API After the needed changes are made to the User-specified Kerberos Descriptor, it must be stored in Ambari. This is done by issuing the following API call to Ambari while adding the changed data as the payload: PUT /api/v1/clusters/{CLUSTER_NAME}/artifacts/kerberos_descriptor NOTE: Be sure to replace {CLUSTER_NAME} when the name of the relevant cluster. This API call can be issued using a command-line tool like curl and the payload can be specified via a local file. For example: curl -u admin:admin -X PUT -d @kerberos_descriptor.json http://localhost:8080/api/v1/clusters/c1/artifacts/kerberos_descriptor NOTE: The user credentials ("-u admin:admin") and cluster name ("c1") should be changed for the particular cluster. After the call completes, the User-specified Kerberos Descriptor stored in the file named kerberos_descriptor.json will be used to update the stored data in the artifact resource. Ambari should realize the changes without restarting.
... View more
