Chapter 14. Synchronizing Template Repositories
Chapter 14. Synchronizing Template Repositories In Satellite, you can synchronize repositories of job templates, provisioning templates, report templates, and partition table templates between Satellite Server and a version control system or local directory. In this chapter, a Git repository is used for demonstration purposes. This section details the workflow for installing and configuring the TemplateSync plug-in and performing exporting and importing tasks. 14.1. Enabling the TemplateSync Plug-in Procedure To enable the plug-in on your Satellite Server, enter the following command: To verify that the plug-in is installed correctly, ensure Administer > Settings includes the TemplateSync menu. 14.2. Configuring the TemplateSync Plug-in In the Satellite web UI, navigate to Administer > Settings > TemplateSync to configure the plug-in. The following table explains the attributes behavior. Note that some attributes are used only for importing or exporting tasks. Table 14.1. Synchronizing Templates Plug-in configuration Parameter API parameter name Meaning on importing Meaning on exporting Associate associate Accepted values: always , new , never Associates templates with OS, Organization, and Location based on metadata. N/A Branch branch Specifies the default branch in Git repository to read from. Specifies the default branch in Git repository to write to. Dirname dirname Specifies the subdirectory under the repository to read from. Specifies the subdirectory under the repository to write to. Filter filter Imports only templates with names that match this regular expression. Exports only templates with names that match this regular expression. Force import force Imported templates overwrite locked templates with the same name. N/A Lock templates lock Do not overwrite existing templates when you import a new template with the same name, unless Force import is enabled. N/A Metadata export mode metadata_export_mode Accepted values: refresh , keep , remove N/A Defines how metadata is handled when exporting: Refresh - remove existing metadata from the template content and generate new metadata based on current assignments and attributes. Keep - retain the existing metadata. Remove - export template without metadata. Useful if you want to add metadata manually. Negate negate Accepted values: true , false Imports templates ignoring the filter attribute. Exports templates ignoring the filter attribute. Prefix prefix Adds specified string to the beginning of the template if the template name does not start with the prefix already. N/A Repo repo Defines the path to the repository to synchronize from. Defines the path to a repository to export to. Verbosity verbose Accepted values: true , false Enables writing verbose messages to the logs for this action. N/A 14.3. Using Repository Sources You can use existing repositories or local directories to synchronize templates with your Satellite Server. 14.3.1. Synchronizing Templates with an Existing Repository Use this procedure to synchronize templates between your Satellite Server and an existing repository. Procedure If you want to use HTTPS to connect to the repository and you use a self-signed certificate authentication on your Git server, validate the certificate: If you want to use SSH to connect to the repository, perform the following steps: Create an SSH key pair if you do not already have it. Do not specify a passphrase. Configure your version control server with the public key from your Satellite, which resides in /usr/share/foreman/.ssh/id_rsa.pub . Accept the Git SSH host key as the foreman user: Configure the TemplateSync plug-in settings on a TemplateSync tab. Change the Branch setting to match the target branch on a Git server. Change the Repo setting to match the Git repository. For example, for the repository located in git@git.example.com/templates.git set the setting into git@git.example.com/templates.git . 14.3.2. Synchronizing Templates with a Local Directory Synchronizing templates with a local directory is useful if you have configured a version control repository in the local directory. That way, you can edit templates and track the history of edits in the directory. You can also synchronize changes to Satellite Server after editing the templates. Prerequisites Each template must contain the location and organization that the template belongs to. This applies to all template types. Before you import a template, ensure that you add the following section to the template: Procedure In /var/lib/foreman , create a directory for storing templates: Note You can place your templates to a custom directory outside /var/lib/foreman , but you have to ensure that the Foreman service can read its contents. The directory must have the correct file permissions and the foreman_lib_t SELinux label. Change the owner of the new templates directory to the foreman user: Change the Repo setting on the TemplateSync tab to match the /var/lib/foreman/ My_Templates_Dir / directory. 14.4. Importing and Exporting Templates You can import and export templates using the Satellite web UI, Hammer CLI, or Satellite API. Satellite API calls use the role-based access control system, which enables the tasks to be executed as any user. You can synchronize templates with a version control system, such as Git, or a local directory. 14.4.1. Importing Templates You can import templates from a repository of your choice. You can use different protocols to point to your repository, for example /tmp/dir , git://example.com , https://example.com , and ssh://example.com . Note The templates provided by Satellite are locked and you cannot import them by default. To overwrite this behavior, change the Force import setting in the TemplateSync menu to yes or add the force parameter -d '{ "force": "true" }' to the import command. Prerequisites Each template must contain the location and organization that the template belongs to. This applies to all template types. Before you import a template, ensure that you add the following section to the template: To use the CLI instead of the Satellite web UI, see the ]. To use the API, see the xref:api_Importing_Templates_managing-hosts[ . Procedure In the Satellite web UI, navigate to Hosts > Sync Templates . Click Import . Each field is populated with values configured in Administer > Settings > TemplateSync . Change the values as required for the templates you want to import. For more information about each field, see Section 14.2, "Configuring the TemplateSync Plug-in" . Click Submit . The Satellite web UI displays the status of the import. The status is not persistent; if you leave the status page, you cannot return to it. CLI procedure To import a template from a repository, enter the following command: For better indexing and management of your templates, use --prefix to set a category for your templates. To select certain templates from a large repository, use --filter to define the title of the templates that you want to import. For example --filter '.*Ansible DefaultUSD' imports various Ansible Default templates. API Procedure Send a POST request to api/v2/templates/import : If the import is successful, you receive {"message":"Success"} . 14.4.2. Exporting Templates Use this procedure to export templates to a git repository. To use the CLI instead of the Satellite web UI, see the ]. To use the API, see the xref:api_Exporting_Templates_managing-hosts[ . Procedure In the Satellite web UI, navigate to Hosts > Sync Templates . Click Export . Each field is populated with values configured in Administer > Settings > TemplateSync . Change the values as required for the templates you want to export. For more information about each field, see Section 14.2, "Configuring the TemplateSync Plug-in" . Click Submit . The Satellite web UI displays the status of the export. The status is not persistent; if you leave the status page, you cannot return to it. CLI procedure To export the templates to a repository, enter the following command: Note This command clones the repository, makes changes in a commit, and pushes back to the repository. You can use the --branch " My_Branch " option to export the templates to a specific branch. API Procedure Send a POST request to api/v2/templates/export : If the export is successful, you receive {"message":"Success"} . Note You can override default API settings by specifying them in the request with the -d parameter. The following example exports templates to the git.example.com/templates repository: 14.5. Uninstalling the Foreman Templates Plug-in To avoid errors after removing the foreman_templates plugin: Procedure Disable the plug-in using the Satellite installer: Clean custom data of the plug-in. The command does not affect any templates that you created. Uninstall the plug-in:
satellite-installer --enable-foreman-plugin-templates sudo -u foreman git config --global http.sslCAPath Path_To_My_Certificate sudo -u foreman ssh-keygen sudo -u foreman ssh git.example.com <%# kind: provision name: My_Provisioning_Template oses: - My_first_OS - My_second_OS locations: - My_first_Location - My_second_Location organizations: - My_first_Organization - My_second_Organization %> mkdir /var/lib/foreman/ My_Templates_Dir chown foreman /var/lib/foreman/ My_Templates_Dir <%# kind: provision name: My_Provisioning_Template oses: - My_first_OS - My_second_OS locations: - My_first_Location - My_second_Location organizations: - My_first_Organization - My_second_Organization %> hammer import-templates --branch " My_Branch " --filter '.* Template NameUSD ' --organization " My_Organization " --prefix "[ Custom Index ] " --repo " https://git.example.com/path/to/repository " curl -H "Accept:application/json" -H "Content-Type:application/json" -u login : password -k https:// satellite.example.com /api/v2/templates/import -X POST hammer export-templates --organization " My_Organization " --repo " https://git.example.com/path/to/repository " curl -H "Accept:application/json" -H "Content-Type:application/json" -u login : password -k https:// satellite.example.com /api/v2/templates/export -X POST curl -H "Accept:application/json" -H "Content-Type:application/json" -u login:password -k https:// satellite.example.com /api/v2/templates/export -X POST -d "{\"repo\":\"git.example.com/templates\"}" satellite-installer --no-enable-foreman-plugin-templates foreman-rake templates:cleanup satellite-maintain packages remove foreman-plugin-templates