Red Hat Ansible Lightspeed with IBM watsonx Code Assistant User Guide

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant 2.x_latest

Learn how to use Red Hat Ansible Lightspeed with IBM watsonx Code Assistant.

Red Hat Customer Content Services

Abstract

This guide shows you how to use Red Hat Ansible Lightspeed with IBM watsonx Code Assistant.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Introduction to Red Hat Ansible Lightspeed

Learn about Red Hat Ansible Lightspeed with IBM watsonx Code Assistant, its benefits, key features, process, and data gathered to train the IBM watsonx Code Assistant models.

1.1. About Red Hat Ansible Lightspeed

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant is a generative AI service that helps automation teams create, adopt, and maintain Ansible content more efficiently. It uses natural language prompts to generate code recommendations for automation tasks based on Ansible best practices.

Red Hat Ansible Lightspeed is the cloud service that enables integration of generative AI into Ansible Automation Platform. This document specifically describes the integration of Red Hat Ansible Lightspeed with IBM watsonx Code Assistant.

Red Hat Ansible Lightspeed uses IBM watsonx Code Assistant models trained on subject matter expertise across the Ansible ecosystem, which includes Galaxy, GitHub, and Ansible certified and validated content. For ease of use, Red Hat Ansible Lightspeed is integrated with your existing Ansible developer workflows. For example, you can use your existing Git repositories (both public and private) to train your IBM watsonx Code Assistant models. You can also access Lightspeed content suggestions in VS Code through the Ansible VS code extension.

1.1.1. Accessing Red Hat Ansible Lightspeed with IBM watsonx Code Assistant

To use Red Hat Ansible Lightspeed with IBM watsonx Code Assistant, your organization must have:

  • A trial or paid subscription to Ansible Automation Platform
  • A trial or paid subscription to IBM watsonx Code Assistant

1.1.2. Benefits of using Red Hat Ansible Lightspeed

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant offers the following benefits:

  • Reduces the onboarding learning period for Ansible developers

    With just a basic understanding of YAML syntax, Ansible developers can use natural language prompts in English language to describe the automation goal. Red Hat Ansible Lightspeed then offers Ansible code recommendations to help achieve the automation goal more efficiently. This combination of content and best practice suggestions reduces the learning curve and offers a smoother onboarding experience for new Ansible users.

    For example, to get a multitask code recommendation, you can enter the prompt Install postgresql-server & run postgresql-setup command. The Ansible Lightspeed service reads the text, interacts with IBM watsonx Code Assistant, and generates code recommendations to automate a multitask that installs a PostgreSQL server and sets up a PostgreSQL database. You can then view and accept the code recommendations to create tasks in an Ansible YAML file.

  • Increases productivity with quality content creation

    Red Hat Ansible Lightspeed offers automation code recommendations that adhere to Ansible best practices, and IBM watsonx Code Assistant provides model fine-tuning features to improve the accuracy of suggested content based on your organization’s existing Ansible content. Therefore, the AI-generated code recommendations are more accurate, more reliable, and integrated with your existing automation development workflows.

  • Extends trust with AI-generated code recommendations

    The AI-generated code recommendations enable you to extend trust, with an automation code base that adheres to accepted Ansible best practices and significant data safeguards.

1.2. Key features of Red Hat Ansible Lightspeed

Red Hat Ansible Lightspeed offers the following key features:

  • Ansible-specific IBM watsonx Code Assistant models

    Red Hat Ansible Lightspeed with IBM watsonx Code Assistant uses Ansible-specific IBM watsonx Granite models unique to your organization, which are provided, managed, and maintained by IBM.

  • Single tasks and multitask generation

    Using natural language prompts, you can generate single task or multiple task recommendations for Ansible task files and playbooks. To request multitask code recommendations, you can enter a sequence of natural language task prompts in a YAML file comment separated by ampersand (&) symbols.

    Currently, Red Hat Ansible Lightspeed supports user prompts in English language only. However, there could be instances where the training data that was used to train the IBM watsonx Code Assistant models included non-English language. In such scenarios, the model can generate code recommendations for prompts made in the same non-English language, but the generated code recommendations might or might not be accurate.

  • Content source matching

    For each generated code recommendation, Red Hat Ansible Lightspeed lists content source matches, including details such as potential source, content author, and relevant licenses. You can use this data to gain insight into potential training data sources used to generate the code recommendations.

  • Post-processing capabilities

    Red Hat Ansible Lightspeed offers post-processing capabilities that augment IBM watsonx Code Assistant and improve the quality and accuracy of code recommendations.

  • Content maintenance and modernization

    The Ansible code bot scans existing content collections, roles, and playbooks through Git repositories, and proactively creates pull requests whenever best practices or quality improvement recommendations are available. The bot automatically submits pull requests to the repository, which proactively alerts the repository owner to a recommended change to their content.

1.3. Using Red Hat Ansible Lightspeed with IBM watsonx Code Assistant

Prerequisites

To use Red Hat Ansible Lightspeed, ensure that you have the following components:

  • Trial or paid subscription to Ansible Automation Platform
  • Trial or paid subscription to IBM watsonx Code Assistant
  • VS Code version 1.70.1 or later
  • The Ansible extension for VS Code version 2.8 or later

1.3.1. Process for using Red Hat Ansible Lightspeed

1.4. Data gathered to train the IBM watsonx Code Assistant models

1.4.1. Models

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant uses Ansible-specific IBM watsonx Granite models unique to your organization. These models are provided, managed, and maintained by IBM.

1.4.2. Data sources

IBM watsonx Code Assistant models are trained on Ansible content from Ansible Galaxy, data from public Git repositories, and Red Hat Ansible subject matter expert examples.

If you publish content to Ansible Galaxy and want to restrict your Ansible Galaxy content from being used to train the models, you can opt out of sharing your Ansible Galaxy data in the Ansible Galaxy namespace configuration.

1.4.3. Data telemetry

Red Hat Ansible Lightspeed collects the following telemetry data by default:

  • Operational telemetry data

    This is the data that is required to operate and troubleshoot the Ansible Lightspeed service. For more information, refer the Enterprise Agreement. You cannot disable the collection of operational telemetry data.

  • Admin dashboard telemetry data

    This is the data that provides insight into how your organization users are using the Ansible Lightspeed service, and the metrics are displayed on the Admin dashboard. You can also disable the Admin dashboard telemetry if you no longer want to collect and monitor the telemetry data. For more information about Admin dashboard telemetry, see Viewing and managing Admin dashboard telemetry.

1.4.4. Telemetry data collection notice for the Admin dashboard

In connection with your use of this Red Hat offering, Red Hat may collect telemetry data about your use of the software. This data allows Red Hat to monitor the software and to improve Red Hat offerings and support, including identifying, troubleshooting, and responding to issues that impact users. The data may also be used to enable you to track your entitlements to Red Hat subscriptions and take advantage of future Red Hat purchasing programs. It may also allow Red Hat to assist you in implementing upgrades to minimize service impact. The data may be shared internally within Red Hat to improve the user experience. If you are evaluating Red Hat software, the data will help Red Hat determine if you need assistance.

1.4.4.1. What information does Red Hat collect?

Tools within the software monitor various metrics and this information is transmitted to Red Hat. The following metrics are monitored:

  • Organization you are logged into (Organization ID, account number)
  • Large language model (or models) that you are connected to
  • Prompts and content suggestions, including accept or reject of the content suggestions
  • User sentiment feedback

1.4.4.2. Personal Data

Red Hat does not intend to collect personal information. If Red Hat discovers that personal information has been inadvertently received, Red Hat will delete such information. To the extent that any telemetry data constitutes personal data, refer the Red Hat Privacy Statement for more information about Red Hat’s privacy practices.

1.4.4.2.1. Retention

Red Hat retains and stores telemetry data only for as long as it’s needed for the purposes described above or as otherwise required or permitted by law.

1.4.4.2.2. Data Security

Red Hat employs technical and organizational measures designed to protect the telemetry data. Data stored in the Red Hat cloud is being protected, where possible, through encryption. Data is also segmented, and therefore is not accessible across organizations.

1.4.4.2.3. Data Sharing

Red Hat may share telemetry data with its business partners in an aggregated form that does not identify customers to help the partners better understand their markets and their customer’s use of Red Hat offerings or ensure the successful integration of products jointly supported by those partners.

1.4.4.2.4. Third Party Service Providers

Red Hat may engage certain service providers to assist in the collection and storage of the telemetry data.

1.4.4.2.5. User Control/ Enabling and Disabling Admin Dashboard Telemetry Collection

You cannot disable collection of operational telemetry data. Operational telemetry data includes only data that is necessary to operate and troubleshoot the service. However, you can disable the collection of Admin Dashboard telemetry data. For more information, see Disabling the Admin dashboard telemetry.

Chapter 2. Logging into the Ansible Lightspeed administrator portal

As a Red Hat account organization administrator, you can use the Ansible Lightspeed administrator portal to configure settings to connect Red Hat Ansible Lightspeed to IBM watsonx Code Assistant.

2.1. Logging in to the Ansible Lightspeed administrator portal

Prerequisites

  • You have organization administrator privileges to a Red Hat Customer Portal organization with a valid Red Hat Ansible Automation Platform subscription.

Procedure

  1. Log in to the Ansible Lightspeed portal as an organization administrator.
  2. Click Log inLog in with Red Hat.
  3. Enter your Red Hat account username and password. The Ansible Lightspeed Service uses Red Hat Single Sign-On (RH-SSO) for authentication.

    As part of the authentication process, the Ansible Lightspeed Service checks whether your organization has an active Ansible Automation Platform subscription. On successful authentication, the login screen is displayed along with your username and your assigned user role.

  4. From the login screen, click Admin Portal.

    You are redirected to the Red Hat Ansible Lightspeed with IBM watsonx Code Assistant administrator portal where you can connect Red Hat Ansible Lightspeed to your IBM watsonx Code Assistant instance.

Chapter 3. Configuring Red Hat Ansible Lightspeed to connect with IBM watsonx Code Assistant

As a Red Hat customer portal administrator, you must configure Red Hat Ansible Lightspeed to connect to your IBM watsonx Code Assistant instance.

3.1. About the Watsonx Code Assistant key and model ID

You need the following IBM watsonx Code Assistant information to connect Red Hat Ansible Lightspeed to your IBM watsonx Code Assistant:

  • Watsonx Code Assistant (WCA) API key

    A WCA API key authenticates all requests made from Red Hat Ansible Lightspeed to IBM watsonx Code Assistant. Each Red Hat organization with a valid Ansible Automation Platform subscription must have a configured WCA API key. When an authenticated RH-SSO user creates a task request in Red Hat Ansible Lightspeed, the WCA API key associated with the user’s Red Hat organization is used to authenticate the request to IBM watsonx Code Assistant.

  • Model ID

    A unique WCA model ID identifies an IBM watsonx Code Assistant model in your IBM Cloud account. The model ID that you configure in the Ansible Lightspeed administrator portal is used as the default model, and can be accessed by all Ansible Lightspeed users within your organization.

Important

You must configure both the WCA key and the model ID when you are initially configuring Red Hat Ansible Lightspeed.

3.2. Connecting Red Hat Ansible Lightspeed to IBM watsonx Code Assistant

Prerequisites

  • You have obtained a WCA API key and a model ID from the IBM watsonx Code Assistant that you want to use in Red Hat Ansible Lightspeed.

    For information about how to obtain a WCA API key and model ID from IBM watsonx Code Assistant, see the IBM watsonx Code Assistant documentation.

Procedure

  1. Log in to the Ansible Lightspeed portal as an organization administrator.
  2. From the login screen, click Admin Portal.
  3. Specify the WCA key of your IBM watsonx Code Assistant instance:

    1. Under IBM Cloud API Key, click Add API key. A screen to enter the API Key is displayed.
    2. Enter the API Key.
    3. Optional: Click Test to validate the WCA key.
    4. Click Save.
  4. Specify the model ID of the model that you want to use:

    1. Click Model Settings.
    2. Under Model ID, click Add Model ID. A screen to enter the Model Id is displayed.
    3. Enter the Model ID that you obtained in the previous procedure as the default model for your organization.
    4. Optional: Click Test model ID to validate the model ID.
    5. Click Save.

      When the WCA API key and model ID is successfully validated, Red Hat Ansible Lightspeed is connected to your IBM watsonx Code Assistant instance.

3.2.1. Additional resources

Chapter 4. Logging in and out of the Ansible Lightspeed portal

You can access Ansible Lightspeed through the Ansible Lightspeed portal. After you enter your Red Hat Single Sign-On (RH-SSO) account credentials, your account is authenticated and you are granted access. Your assigned user role is displayed on the login screen of the Ansible Lightspeed portal.

Table 4.1. User login scenarios

ScenarioResult

You are a RH-SSO user.
NOTE: This is the typical scenario for accessing Red Hat Ansible Lightspeed as an Ansible user.

You are routed to the Red Hat Ansible Lightspeed paid commercial offering.

You are a RH-SSO user, but your organization administrator has not configured Red Hat Ansible Lightspeed to connect with IBM watsonx Code Assistant.

You are routed to the Red Hat Ansible Lightspeed paid commercial offering with a message that your organization administrator has not configured a model for your organization.

4.1. Logging in to the Ansible Lightspeed portal

Procedure

  1. Go to the Ansible Lightspeed portal login page.
  2. Click Log inLog in with Red Hat.
  3. Enter your Red Hat account username and password.

On successful authentication, the login screen is displayed along with your username and your assigned user role.

4.2. Logging out of the Ansible Lightspeed portal

To log out of the Ansible Lightspeed Service, you must log out of both the Ansible Lightspeed VS Code extension and the Ansible Lightspeed portal.

Procedure

  • Log out of the Ansible Lightspeed VS Code extension:

    • Click the Person icon Person icon . You will see a list of accounts that VS Code is logged into.
    • Select Ansible LightspeedSign Out.
  • Log out of the Ansible Lightspeed portal:

Chapter 5. Installing and configuring the Ansible VS Code extension

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant is integrated with the Ansible Visual Studio (VS) Code extension in VS Code. The Ansible VS Code extension, with Red Hat Ansible Lightspeed features enabled, automatically collects recommendations, usage telemetry, and Ansible YAML file state through automated events.

To access Red Hat Ansible Lightspeed, all Ansible users must install and configure the Ansible VS Code extension in their VS Code. The Ansible VS Code extension uses the Ansible-specific IBM watsonx Granite model configured in the Red Hat Ansible Lightspeed administrator portal as the default mode for all users in your organization.

You can also use a custom, fine-tuned model if your organization administrator has created a custom model and has shared the model ID with you separately. You use the model-override setting in the Ansible VS Code extension to override the default model, and use the custom model instead. Using a custom model enables you to improve the code recommendation experience and tune the model to your organizational automation patterns. For example, if you are using Red Hat Ansible Lightspeed both as an organization administrator and an user, you can test the custom model for select Ansible users before making it available for all users in your organization. For more information, see Configuring custom models.

5.1. Installing the Ansible VS Code Extension

Prerequisites

  • VS Code version 1.70.1 or later.
Note

You can also install VScode derivatives, such as VScode Insider or VS Codium.

Procedure

  1. Open the VS Code application.
  2. From the navigation menu, click the Extensions icon.
  3. In the Search field, enter Ansible.
  4. Select Ansible to choose the Ansible language support extension published by Red Hat.
  5. Click Install.
  6. After installation is complete, verify your VSCode installation:

    1. Create a new YAML file using the .yml or .yaml file extension.
    2. From the Status toolbar, click the language indicator and select Ansible to associate the Ansible language type with the new YAML file.
    3. Start writing a test playbook. Contextual aids are displayed as you start creating your content.

5.2. Configuring the Ansible VS Code extension

You can configure the Ansible VS Code extension to enable Red Hat Ansible Lightspeed and specify it’s portal URL and WCA model ID.

Prerequisites

  • Your organization administrator has configured an IBM watsonx Code Assistant model for your organization.

Procedure

  1. Open the VS Code application.
  2. From the Activity bar, click the Extensions icon Extensions .
  3. From the Installed Extensions list, select Ansible.
  4. From the Ansible extension page, click the Settings icon and select Extension Settings.
  5. Select Ansible Lightspeed settings, and specify the following information:

    1. Select the Enable Ansible Lightspeed checkbox.
    2. In the URL for Ansible Lightspeed field, verify that you have the following URL: https://c.ai.ansible.redhat.com/.
    3. Select the Enable Ansible Lightspeed with watsonx Code Assistant inline suggestions checkbox.
  6. Optional: If you want to use the custom model instead of the default model, in the Model ID Override field, enter the custom model ID. The model-override setting enables you to override the default model and use the custom model, after your organization administrator has created a custom model and has shared the model ID with you separately.

    Your settings are automatically saved in VS Code.

The following illustration displays the configured settings for the Ansible VS Code extension:

Figure 5.1. Configured settings for the Ansible VS Code extension

Configured settings for the Ansible VS Code extension

5.3. Logging in to Ansible Lightspeed through the Ansible VS Code extension

After installing and configuring the VS Code extension, you can log in to the Ansible Lightspeed service.

Procedure

  1. Open the VS Code application.
  2. Use one of the following ways to connect to the Ansible Lightspeed service.

    • Using the Connect button:

      1. From the navigation menu, click the Ansible icon.
      2. Under Ansible Lightspeed Login, click Connect.
    • Using the Accounts button:

      1. From the navigation menu, click Accounts icon > Sign in with Ansible Lightspeed.

        Note

        This option is displayed when the VS Code extension is in an active state. The extension is activated after you open the Ansible side panel or after you open an Ansible file in the VS Code editor. If you do not see this option, use the Connect button to link to the Ansible Lightspeed service.

  3. When prompted, click Allow to sign in.
  4. In the Authorize Ansible Lightspeed for VS Code window, click Authorize.
  5. In the Do you want Code to open the external website? window, click Open. The Ansible Lightspeed portal login page is displayed.
  6. Click Log in → Log in with Red Hat.
  7. Enter your Red Hat account username and password.

    On successful authentication, the login screen is displayed along with your username and your assigned user role. The VS code extension is now connected with Ansible Lightspeed service.

Chapter 6. Requesting task recommendations

Red Hat Ansible Lightspeed is integrated into Visual Studio (VS) Code through the Ansible VS Code extension. You can request code recommendations for your task intent by using Ansible VS Code extension.

6.1. Overview

You can perform the following tasks from the Ansible VS Code extension:

  • Create single task or multitask requests by using natural language prompts

    • Create a single task prompt

      Write a description of your task in the - name: key of a new task line in your Ansible file. For example, to automate a task of installing PostgreSQL server, you can enter the prompt - name: Install postgresql-server.

    • Create a multitask prompt

      Place your cursor on a new line in your Ansible YAML file at the correct indentation, and start your prompt with a Pound key (#).

      Write the descriptions of your tasks, separating each prompt by using Ampersand symbols (&). For example, to automate a multitask of installing PostgreSQL server and running the initial PostgreSQL setup command, you can enter the prompt # Install postgresql-server & run postgresql-setup command.

      The Ansible Lightspeed service reads the text, interacts with the IBM watsonx Code Assistant model, and generates Ansible task recommendations based on your natural language prompt.

      Note

      Currently, Red Hat Ansible Lightspeed supports user prompts in English language only. However, there could be instances where the training data that was used to train the IBM watsonx Code Assistant models included non-English language. In such scenarios, the model can generate code recommendations for prompts made in the same non-English language, but the generated code recommendations might or might not be accurate.

  • View the content source matching results

    For each generated code recommendation, Red Hat Ansible Lightspeed lists content source matches, including details such as potential source, content author, and relevant licenses. You can use this data to gain insight into potential training data sources used to generate the code recommendations.

  • Provide feedback on the Ansible Lightspeed service

    The Ansible Lightspeed service learns your organizational patterns and improves the code recommendation experience over time. You can provide feedback on whether the generated code recommendations were suitable for your task intent. This feedback enables Red Hat Ansible Lightspeed with IBM watsonx Code Assistant to improve on the quality of its suggestions.

6.2. Requesting code recommendations for a single task

You can request code recommendations for a single task by entering natural language prompts in Ansible VS Code extension. For example, to automate a task of installing a PostgreSQL server, you can enter the prompt - name: Install postgresql-server. The Ansible Lightspeed service reads the text, interacts with the IBM watsonx Code Assistant model, and generates the code recommendations.

Prerequisites

Procedure

  1. Log in to VS Code with your Red Hat account.
  2. Create a new YAML file or use an existing YAML file:

    • Create a YAML file:

      1. Select FileNew Text File.
      2. From the lower right of the screen, click Plain Text, and in the language mode, select Ansible.
      3. Save the file as a YAML file format extension (.yml or .yaml).
    • Use an existing YAML file:

      1. On the bottom right of the screen, click the existing language mode, and in the language mode settings, select Ansible.

        Note

        If you do not see the language mode section in your VS Code editor, from the Command Palette, select Configure Langauge ModeAnsible.

  3. Verify that you see an entry for Lightspeed on the status bar at the lower right of VS Code.

    If Ansible is already selected as the desired language but the Lightspeed entry is not displayed, re-select Ansible as the language mode. The following illustration shows Lightspeed and Ansible entries on the VS Code status bar.

    Figure 6.1. Ansible and Lightspeed set as selected language mode

    Settings show Ansible and Lightspeed as selected language mode
  4. Optional: If you see an error message about missing Ansible lint, you can install the missing module or disable it. Perform any one of the following tasks:

    • Install Ansible lint: For installation information, see the Installing section of the Ansible Lint documentation.
    • Disable Ansible lint:

      1. From the Activity bar, click the Extensions icon Extensions .
      2. From the Installed extensions list, select Ansible.
      3. From the Ansible extension page, click the Settings icon and select Extension Settings.
      4. Clear the Ansible › Validation › Lint: Enabled checkbox.
  5. Create a playbook or use an existing playbook.

    For more information, see Creating playbooks in the Ansible Automation Platform Creator Guide.

  6. In the playbook, provide the following information to request code recommendations for a single task:

    1. Add a new Ansible task by starting a new line with - name: at the correct indentation.
    2. Add a detailed natural language prompt in the task description after - name: on the same line. For example, you can specify the following single task prompt: - name: Install postgresql-server
    3. Press Enter directly after the task description. Keep the cursor at the same location in your file, and wait for the code recommendation results to populate.

      The Ansible Lightspeed service is engaged, and it starts generating code recommendations for a single task.

      Important

      Ansible Lightspeed service takes around 5 seconds per task to populate the code recommendations. If you are using a multitask prompt, the Ansible Lightspeed service takes a bit longer (number of tasks times 5 seconds) to populate the results. Do not move your cursor or press any key while the code recommendation is being generated. If you change the cursor location or press any key, Ansible VS Code extension cancels the request and the Ansible Lightspeed service does not process your request.

      When the Ansible Lightspeed service is engaged, a Lightspeed processing status indicator is displayed in the lower right of the screen to denote that your code recommendation is being generated.

      Lightspeed icon

  7. View your code recommendations and ensure that the recommendations match your task intent.

    The following illustration shows the code recommendations generated by the Ansible Lightspeed service for the single task Install postgresql-server:

    Lightspeed single task in progress

  8. Accept or reject the code recommendations:

    • To accept a code recommendation, press Tab.
    • To reject a code recommendation, press Esc.

      Note

      If you reject a recommendation, you can modify the prompt and review the generated code recommendations once again to match your task intent.

  9. On the ANSIBLE: LIGHTSPEED TRAINING MATCHES tab, view the content source matching results.

    The following illustration shows the training matches found in existing Ansible Galaxy content for the task prompt Install postgresql-server:

    training matches in existing content
  10. Click Save to save the code recommendation changes in your Ansible YAML file.

6.3. Requesting code recommendations for multiple tasks

You can request multitask code recommendations by entering a sequence of natural language task prompts in Ansible VS Code extension. In a YAML file, start a comment by using a Pound key (#), and separate each prompt by using Ampersand (&) symbols.

For example, to automate a multitask of installing PostgreSQL server and running the initial PostgreSQL setup command, you can enter the prompt # Install postgresql-server & run postgresql-setup command. The Ansible Lightspeed service reads the text, interacts with the IBM watsonx Code Assistant models, and generates the code recommendations.

Prerequisites

Procedure

  1. Log in to VS Code with your Red Hat account.
  2. Create a new YAML file or use an existing YAML file.

    • Create a YAML file:

      1. Select FileNew Text File.
      2. From the lower right of the screen, click Plain Text, and in the language mode, select Ansible.
      3. Save the file as a YAML file format extension (.yml or .yaml).
    • Use an existing YAML file:

      1. On the bottom right of the screen, click the existing language mode, and in the language mode settings, select Ansible.

        Note

        If you do not see the language mode section in your VS Code editor, from the Command Palette, select Configure Langauge ModeAnsible.

  3. Verify that you see an entry for Lightspeed on the status bar at the lower right of VS Code.

    If Ansible is already selected as the desired language but the Lightspeed entry is not displayed, re-select Ansible as the language mode. The following illustration shows Lightspeed entry on the VS Code status bar.

    Figure 6.2. Ansible and Lightspeed set as selected language mode

    Settings show Lightspeed as selected language mode
  4. Optional: If you see an error message about missing Ansible lint, you can install the missing module or disable it. Perform any one of the following tasks:

    • Install Ansible lint: For installation information, see the Installing section of the Ansible Lint documentation.
    • Disable Ansible lint:

      1. From the Activity bar, click the Extensions icon Extensions .
      2. From the Installed extensions list, select Ansible.
      3. From the Ansible extension page, click the Settings icon and select Extension Settings.
      4. Clear the Ansible › Validation › Lint: Enabled checkbox.
  5. Create a playbook or use an existing playbook.

    For more information, see Creating playbooks in the Ansible Automation Platform Creator Guide.

  6. In the playbook, provide the following information to request multitask code recommendations:

    1. Start a new YAML file comment by entering a Pound key (#) at the correct indentation.
    2. Add a detailed natural language prompt in a sequence, separating each task by using an Ampersand (&) symbol. For example, to automate the multitask of installing PostgreSQL server and running the PostgreSQL setup command, enter the following natural language prompt # Install postgresql-server & run postgresql-setup command.
    3. Press Enter directly after the task description. Keep the cursor at the same location in your file, and wait for the code recommendation results to populate.

      The Ansible Lightspeed service is engaged, and it starts generating code recommendations for multiple tasks.

      Important

      Ansible Lightspeed service takes around 5 seconds per task to populate the code recommendations. If you are using a multitask prompt, the Ansible Lightspeed service takes a bit longer (number of tasks times 5 seconds) to populate the results. Do not move your cursor or press any key while the code recommendation is being generated. If you change the cursor location or press any key, Ansible VS Code extension cancels the request and the Ansible Lightspeed service does not process your request.

      When the Ansible Lightspeed service is engaged, a Lightspeed processing status indicator is displayed in the lower right of the screen to denote that your code recommendation is being generated.

      Lightspeed icon

  7. Optional: If multitask code recommendations are not being generated, log out of VS Code and log in again using your Red Hat account.
  8. View your code recommendations and ensure that the recommendations match your task intent.

    The following illustration shows the code recommendations generated by the Ansible Lightspeed service for the multitask prompt Install postgresql-server & run postgresql-setup command: :

    Lightspeed single task in progress

  9. Accept or reject the code recommendations:

    • To accept a code recommendation, press Tab.
    • To reject a code recommendation, press Esc.

      Note

      If you reject a recommendation, you can modify the prompt and review the generated code recommendations once again to match your task intent.

  10. On the ANSIBLE: LIGHTSPEED TRAINING MATCHES tab, view the content source matching results.

    The following illustration shows the training matches found in existing Ansible Galaxy content for the task prompt multitask prompt Install postgresql-server & run postgresql-setup command:

    training matches in existing content
  11. Click Save to save the code recommendation changes in your Ansible YAML file.

6.4. Viewing Ansible Lightspeed training matches

The Red Hat Ansible Lightspeed with IBM watsonx Code Assistant machine learning model is trained on the following content: * Existing public or private Git repositories * Content from Ansible Galaxy

Owing to IBM watsonx Code Assistant’s generative AI technology, as well as the types of Ansible content that were used to train the model, it is not possible to identify the specific set of training data that contributed to the generated code recommendations. However, Ansible Lightspeed provides a capability that helps you to understand the possible origins of generated code recommendations.

For each generated code recommendation, Red Hat Ansible Lightspeed lists the content source matches, including details such as potential source, content author, and relevant licenses. You can use this data to gain insight into potential training data sources used to generate the code recommendations.

After you enter a natural language prompt in VS Code and see the generated code recommendations, you can view the content source matches on the ANSIBLE: LIGHTSPEED TRAINING MATCHES tab.

For example, the following illustration shows the training matches for the multitask recommendation Install postgresql-server & run postgresql-setup command:

Figure 6.3. Training matches for a multitask recommendation

Training matches for multitask recommendation

This capability enables you to find out the open source license terms that are associated with related training data. However, it is unlikely that either the training data used in fine-tuning the code or the output recommendations themselves are protected by copyright, or that the output reproduces training data that is controlled by copyright licensing terms.

Note

Red Hat does not claim any copyright or other intellectual property rights in the suggestions generated by Red Hat Ansible Lightspeed with IBM watsonx Code Assistant.

6.5. Providing feedback on the Ansible Lightspeed service

Red Hat Ansible Lightspeed with IBM watsonx Code Assistant is designed to be improved through feedback on the quality of its suggestions. The technical details of user experiences with Red Hat Ansible Lightspeed are useful in informing further improvements.

You can submit feedback through the following channels:

  • From the Ansible VS Code extension: Use this method to provide feedback about the quality of the suggested code recommendations.

    Important

    Red Hat Support cannot assist with the suggestion quality reports. Content quality issues are routed to IBM for resolution.

  • From the Red Hat customer portal: Use this method to log bug reports and service disruption incidents, and feature requests.
Note

On the login screen of the Ansible Lightspeed Portal, there is a Chat link that redirects you to a Matrix channel. Use the Matrix channel to ask questions pertaining to your Ansible Lightspeed experience and request help to troubleshoot your issues. However, the Matrix channel is not an official Support channel, and issues raised in the Matrix chat would not be tracked through Red Hat Service Level Agreement (SLA). To raise a bug or a feature request, contact Red Hat Support and open a support ticket.

Prerequisites

  • You are part of an organization that has a trial or paid subscription to both Ansible Automation Platform and IBM watsonx Code Assistant.

Procedure

  1. Open Visual Studio Code.
  2. Click the Lightspeed entry in your status bar to see options.
  3. In the Tell us why field, provide your feedback. Here, provide feedback about what results you were expecting to receive, compared to what results were generated and the training match.
  4. Select the issue type: Bug report, Feature request, or Suggestion feedback.

    Note

    To raise a bug or feature request, contact Red Hat Support and open a support ticket. Bug features and feature requests made through Ansible Lightspeed feedback are not tracked through the Red Hat Service Level Agreement (SLA).

  5. Select the I understand that feedback is shared with Red Hat and IBM checkbox.
  6. Click Send.

    The following image shows an example of providing suggestion feedback:

    Figure 6.4. Providing feedback on Ansible Lightspeed

    Providing feedback on Ansible Lightspeed

Chapter 7. Installing and configuring the Ansible code bot

The Ansible code bot scans existing content collections, roles, and playbooks hosted in GitHub repositories, and proactively creates pull requests whenever best practices or quality improvement recommendations are available.

Ansible code bot scans your code repositories to recommend code quality improvements. It promotes Ansible best practices while avoiding common errors that can lead to bugs or make code harder to maintain. The bot automatically submits pull requests to the repository, which proactively alerts the repository owner to a recommended change to their content. You can configure Ansible code bot to scan your existing Git repositories (both public and private). Your organization must have an active subscription to Red Hat Ansible Automation Platform to use the Ansible code bot.

After you install the Ansible code bot, you can access the Ansible code bot dashboard that displays all your repositories that have the bot installed along with their scan status. From the dashboard, you can start a manual scan, view the scan history, and view the repository. From GitHub, you can configure a schedule to scan your repository at regular intervals, and add or remove a repository from being scanned. For more information, see Managing repository scans.

Important

Ansible code bot is supported on the following GitHub versions:

  • GitHub.com
  • GitHub Enterprise Cloud

    Ansible code bot is not supported on GitHub Enterprise Server. For more information, see GitHub’s plans in the GitHub documentation.

The following examples are code recommendations that the Ansible code bot can suggest:

  • Available alternatives for deprecated legacy syntax or implementation patterns
  • Module version changes and updates, such as:

    • Adding any new required parameters
    • Flagging deprecated parameters
    • Removing unused parameters
  • Applying YAML best practices
  • Adding comment blocks
  • Fixing casing issues in name fields

7.1. Installing the Ansible code bot

Install the Ansible code bot to get code recommendations for your repositories, and then log in to the Ansible code bot dashboard to monitor and manage your repository scans.

Procedure

  1. Log in to GitHub by using the account associated with your organization.
  2. Go to the Ansible code bot GitHub app.
  3. Select the Ansible repositories that you want the app to access:

    • All repositories: Provides access to read the metadata of all repositories.
    • Only select repositories: Provides access to read the metadata of only the repositories that you select.
  4. Optional: If you selected Only select repositories in the previous step, select the repositories that you want the Ansible code bot to access from the Select repositories list.
  5. Click Install & Authorize. A message is displayed that specifies the following permissions are granted automatically to the bot during installation:

    • Read access to metadata
    • Read and write access to code and pull requests
  6. When prompted, log in to your Red Hat Single Sign-On account as an organization administrator.
  7. Log in to the Ansible code bot dashboard:

    1. On the Authorize Ansible code bot page, verify your account and repository permissions.
    2. Click Authorize Ansible.

      From the Authorize Ansible code bot page, the following actions occur:

      • Ansible code bot verifies that you are a part of an organization that has an active subscription to Red Hat Ansible Automation Platform.
      • GitHub requests read permissions to access the repositories associated with your account.

On successful authorization, you are logged in to Ansible code bot dashboard that displays all your repositories that have the Ansible code bot installed along with their scan status. If you did not set up a scan schedule earlier, the dashboard displays the repositories without any associated scan history. You can scan your Git repository by starting a manual scan, or configure a schedule to scan your repository at regular intervals. You can also add a repository for scanning or remove an existing repository from being scanned. For more information, see Managing repository scans.

7.1.1. Uninstalling the Ansible code bot

If you no longer want to use the Ansible code bot, you can uninstall it from GitHub. Once uninstalled, you can still access the Ansible code bot dashboard but you cannot see the repositories on the dashboard or scan your repositories.

Procedure

  1. Log in to GitHub by using the account associated with your organization.
  2. In GitHub, click your profile photo > Settings.
  3. Under Integrations, click Applications > Installed GitHub Apps.
  4. Click Configure beside the Ansible code bot app.
  5. Under the Danger zone area, click Uninstall.

    The Ansible code bot app is uninstalled from your GitHub account.

7.2. Managing repository scans

The Ansible code bot dashboard displays a list of your repositories where the code bot is installed, and indicates if the scan schedule is not set, or is set to manual or scheduled scan.

You can scan your Git repository by starting a manual scan, or configure a schedule to scan your repository at regular intervals. After the scan is completed, you can view the scan history (start time, status, type of scan, link to the pull request if it was created, and the log message if the scan failed). You can also add new repositories for scanning or remove existing repositories from being scanned.

7.2.1. Manually scanning your Git repositories

You can manually scan your Git repositories if you did not set up a scanning schedule for your Ansible code bot or if you do not want to wait for the next scheduled scan. If you manually scan your repository, and no pull request was created, it is likely so because a duplicate pull request already exists. You can scan your repository from both the Ansible code bot dashboard and GitHub.

7.2.1.1. Manually scanning the repository from the Ansible code bot dashboard

Procedure

  1. Log in to the Ansible code bot dashboard.

    The Repositories list displays a list of repositories that you selected for scanning.

    Note

    If you do not see your repository in the Repositories list, you can add it for scanning. For more information, see Adding or removing repositories from the Ansible code bot.

  2. To start a manual scan of your repository, click the Ellipsis icon ( Ellipsis icon ) beside the repository that you want to scan and select Scan now.
  3. Click Refresh to view the status of the scan job.
  4. To view more details about your repository scans, click the Ellipsis icon ( Ellipsis icon ) beside the repository and select View scan history.

    The repository’s scan history is displayed along with the scan start time, scan status, type of scan (scheduled or manual), link to the pull request if it was created, and the log message if the scan failed.

  5. To view your repository on GitHub, click the Ellipsis icon ( Ellipsis icon ) beside the repository and select View repository.

7.2.1.2. Manually scanning the repository from GitHub

Procedure

  1. In GitHub, go to the main page of the repository that you want to scan.
  2. To modify the repository settings, click the Settings icon beside the About area.
  3. In the Topics field, enter the keyword topic ansible-code-bot-scan to the repository.

    The following illustration shows the keyword topic for starting a manual scan:

    Ansible code bot settings
  4. Click Save changes.

    Based on the repository webhook event, Ansible code bot starts a manual scan of your repository. If the avoid duplicate pull requests condition is not met, then the manual scan results in a new pull request with all the necessary Ansible code bot recommendations.

7.2.2. Configuring the Ansible code bot to scan your repository at regular intervals

You can schedule the Ansible code bot to scan your repositories at daily, weekly, or monthly intervals. To specify a scan schedule for your repository, create a configuration file ansible-code-bot.yml within your repository and specify your scan schedule in the .yml file.

You can specify one of following interval cadence to scan your Git repositories:

  • Daily: Runs every day from Monday to Sunday.
  • Weekly: Runs once a week. By default, this is on Monday.
  • Monthly: Runs on the first day of the month, once each month.

For each interval cadence, Ansible code bot starts scanning your Git repositories at 9 AM UTC.

Procedure

  1. In GitHub, navigate to the repository that you want to scan.
  2. Create a .yml configuration file named ansible-code-bot.yml in your repository .github folder. For example, .github/ansible-code-bot.yml.
  3. In the configuration file, specify the interval parameter. You can specify the interval parameter as daily, weekly, or monthly. For example:

    schedule:
      interval: "<daily | weekly | monthly>"
  4. Commit your changes.

The Ansible code bot starts scanning your repository per the schedule you configured at 9 AM UTC time.

7.2.3. Viewing your repository’s scan history

Use the Ansible code bot dashboard to see a list of your repositories and their scan history.

Procedure

  1. Log in to the Ansible code bot dashboard.

    The Ansible code bot dashboard displays a list of your repositories where the code bot is installed, and indicates if the scan schedule is not set, or is set to manual or scheduled scan.

  2. To view the history of your repository’s scans, click the Ellipsis icon ( Ellipsis icon ) beside the repository and select View scan history.

    The repository’s scan history is displayed along with the scan start time, scan status, type of scan (scheduled or manual), link to the pull request if it was created, and the log message if the scan failed.

  3. To view your repository on GitHub, click the Ellipsis icon ( Ellipsis icon ) beside the repository and select View repository.

7.2.4. Adding or removing repositories from the Ansible code bot

You can enable the Ansible code bot for a repository, or remove repositories that you no longer want to manage.

Procedure

  1. Log in to the Ansible code bot dashboard.
  2. Click Manage Code Bot on GitHub.
  3. In GitHub, click your profile photo > Settings.
  4. Under Integrations, click Applications.
  5. From the Repository access area, perform one of the following tasks:

    • Add a new repository: From the Select repositories list, select the repository that you want to add. The newly-added repository is displayed on the Ansible code bot dashboard.
    • Remove an existing repository: From the Select repositories list, click the Cross icon beside the repository that you want to delete. The deleted repository details are no longer visible on the Ansible code bot dashboard.
  6. Click Save.

7.3. How Ansible code bot handles duplicate pull requests

  • If Ansible code bot has created a pull request on the latest commit default branch, it does not scan the repository. The bot skips scanning the repository because the pull request was committed on the latest default branch, and no new commit was made after that pull request.
  • If there is an existing pull request that is not on the latest commit default branch, the Ansible code bot does a pull request difference to compare the changes in both branches. The following scenarios are possible:

    • There is no difference in the existing and new scan results: Ansible code bot does not push the scan results as a new pull request.
    • There are differences found in the existing and the new scan results: the Ansible code bot creates a new pull request. The newly-created pull request does not close the existing pull request, against which the pull request difference was noted. This behavior makes it easier for the repository administrator to review only the latest pull request created by the Ansible code bot, and the administrator can avoid reviewing the older pull requests created by the bot. If required, the administrator can close the older pull requests.

Chapter 8. Configuring custom models

As an organization administrator, you can create and use fine-tuned, custom models that are trained on your organization’s existing Ansible content. With this capability, you can tune the models to your organization’s automation patterns and improve the code recommendation experience.

You can configure multiple custom models for your organization. For example, you can create a custom model for your corporate IT automation team and a different one for your engineering team’s infrastructure. You can also configure a custom model to make it available for all Ansible users or select Ansible users in your organization.

8.1. Process for configuring custom models

To configure a custom model, perform the following tasks:

8.2. Creating a training data set by using content parser tool

Use the content parser tool, a command-line interface (CLI) tool, to scan your existing Ansible files and generate a custom model training data set. The training data set includes a list of Ansible files and their paths relative to the project root. You can then upload this data set to IBM watsonx Code Assistant, and use it to create a custom model that is trained on your organization’s existing Ansible content.

8.2.1. Methods of creating training data sets

You can generate a training data set by using one of the following methods:

  • With ansible-lint preprocessing

    By default, the content parser tool generates training data sets by using ansible-lint preprocessing. The content parser tool uses ansible-lint rules to scan your Ansible files and ensure that the content adheres to Ansible best practices. If rule violations are found, the content parser tool excludes these files from the generated output. In such scenarios, you must resolve the rule violations, and run the content parser tool once again so that the generated output includes all your Ansible files.

  • Without ansible-lint preprocessing

    You can generate a training data set without ansible-lint preprocessing. In this method, the content parser tool does not scan your Ansible files for ansible-lint rule violations; therefore, the training data set includes all files. Although the training data set includes all files, it might not adhere to Ansible best practices and could affect the quality of your code recommendation experience.

8.2.2. Supported data sources

The content parser tool scans the following directories and file formats:

  • Local directories
  • Archived files, such as .zip, .tar, .tar.gz, .tar.bz2, and .tar.xz files
  • Git repository URLs (includes both private and public repositories)

8.2.3. Process of creating a training data set

To create a custom model training data set, perform the following tasks:

  1. Install content parser tool on your computer
  2. Generate a custom model training data set
  3. View the generated training data set
  4. (Optional: If you generated a training data set with ansible-lint preprocessing and detected ansible-lint rule violations) Resolve ansible-lint rule violations
  5. (Optional: If you generated multiple training data sets) Merge multiple training data sets into a single JSONL file

8.2.4. Installing content parser tool

Install the content parser tool, a command-line interface (CLI) tool, on your computer.

Prerequisites

Ensure that your computer has one of the following supported OS:

  • Python version 3.10 or later.
  • UNIX OS, such as Linux or Mac OS.

    Note

    Installation of the content parser tool on Microsoft Windows OS is not supported.

    Procedure

    1. Create a working directory and set up venv Python virtual environment:

      $ python -m venv ./venv

      $ source ./venv/bin/activate

    2. Install the latest version of content parser tool from the pip repository:

      $ pip install --upgrade pip

      $ pip install --upgrade ansible-content-parser

    3. Perform one of the following tasks:

      • To generate a training data set without ansible-lint preprocessing, go to section Generating a custom model training data set.
      • To generate a training data set with ansible-lint preprocessing, ensure that you have the latest version of ansible-lint installed on your computer:

        1. View the ansible-lint versions that are installed on your computer.

          $ ansible-content-parser --version

          $ ansible-lint --version

          A list of application versions and their dependencies are displayed.

        2. In the output, verify that the version of ansible-lint that was installed with the content parser tool is the same as that of the previously-installed ansible-lint. A mismatch in the installed ansible-lint versions causes inconsistent results from the content parser tool and ansible-lint.

          For example, in the following output, the content parser tool installation includes ansible-lint version 6.20.0 which is a mismatch from previously-installed ansible-lint version 6.13.1:

          $ ansible-content-parser --version
          ansible-content-parser 0.0.1 using ansible-lint:6.20.0 ansible-core:2.15.4
          $ ansible-lint --version
          ansible-lint 6.13.1 using ansible 2.15.4
          A new release of ansible-lint is available: 6.13.1 → 6.20.0
        3. If there is a mismatch in the ansible-lint versions, deactivate and reactivate venv Python virtual environment:

          $ deactivate

          $ source ./venv/bin/activate

        4. Verify that the version of ansible-lint that is installed with the content parser tool is the same as that of the previously-installed ansible-lint:

          $ ansible-content-parser --version

          $ ansible-lint --version

          For example, the following output shows that both ansible-lint installations on your computer are of version 6.20.0:

          $ ansible-content-parser --version
          ansible-content-parser 0.0.1 using ansible-lint:6.20.0 ansible-core:2.15.4
          $ ansible-lint --version
          ansible-lint 6.20.0 using ansible-core:2.15.4
          ansible-compat:4.1.10 ruamel-yaml:0.17.32 ruamel-yaml-clib:0.2.7

8.2.5. Generating a custom model training data set

After installing content parser tool, run it to scan your custom Ansible files and generate a custom model training data set. The training data set includes a list of Ansible files and their paths relative to the project root. You can then upload the training data set to IBM watsonx Code Assistant and create a custom model for your organization. If you used ansible-lint preprocessing and encountered rule violations, you must resolve the rule violations before uploading the training data set to IBM watsonx Code Assistant.

8.2.5.1. Methods of generating a training data set

You can generate a training data set by using one of the following methods:

  • With ansible-lint preprocessing

    By default, the content parser tool generates training data sets by using ansible-lint preprocessing. The content parser tool uses ansible-lint rules to scan your Ansible files and ensure that the content adheres to Ansible best practices. If rule violations are found, the content parser tool excludes these files from the generated output. In such scenarios, you must resolve the rule violations, and run the content parser tool once again so that the generated output includes all your Ansible files.

  • Without ansible-lint preprocessing

    You can generate a training data set without ansible-lint preprocessing. In this method, the content parser tool does not scan your Ansible files for ansible-lint rule violations; therefore, the training data set includes all files. Although the training data set includes all files, it might not adhere to Ansible best practices and could affect the quality of your code recommendation experience.

Prerequisites

  • You must have installed content parser tool on your computer.
  • You must have verified that the version of ansible-lint that is installed with the content parser tool is the same as that of the previously-installed ansible-lint.

Procedure

  1. Run the content parser tool to generate a training data set:

    • With ansible-lint preprocessing: $ ansible-content-parser source output
    • Without ansible-lint preprocessing: $ ansible-content-parser source output -S

      The following table lists the required parameters.

      ParameterDescription

      source

      Specifies the source of the training data set.

      output

      Specifies the output of the training data set.

      -S or --skip-ansible-lint

      Specifies to skip ansible-lint preprocessing while generating the training data set.

    For example: If the source is a Github URL https://github.com/ansible/ansible-tower-samples.git, and the output directory is /tmp/out, the command prompt is as follows:
    $ ansible-content-parser https://github.com/ansible/ansible-tower-samples.git /tmp/out

  2. Optional: To generate a training data set with additional information, specify the following parameters while running the content parser tool.

    ParameterDescription

    --source-license

    Specifies to include the licensing information of the source directory in the training data set.

    --source-description

    Specifies to include the descriptions of the source directory in the training data set.

    --repo-name

    Specifies to include the repository name in the training data set. If you do not specify the repository name, the content parser tool automatically generates it from the source name.

    --repo-url

    Specifies to include the repository URL in the training data set. If you do not specify the repository URL, the content parser tool automatically generates it from the source URL.

    -v or --verbose

    Displays the console logging information.

    Example of a command prompt for Github repository ansible-tower-samples

    $ ansible-content-parser --profile min \
    --source-license undefined \
    --source-description Samples \
    --repo-name ansible-tower-samples \
    --repo-url 'https://github.com/ansible/ansible-tower-samples' \
    git@github.com:ansible/ansible-tower-samples.git /var/tmp/out_dir

    Example of a generated training data set for Github repository ansible-tower-samples

    The training data set is formatted with Jeff Goldblum (jg), a command-line JSON processing tool.

    $ cat out_dir/ftdata.jsonl| jq
    {
    "data_source_description": "Samples",
    "input": "---\n- name: Hello World Sample\n hosts: all\n tasks:\n - name: Hello Message",
    "license": "undefined",
    "module": "debug",
    "output": " debug:\n msg: Hello World!",
    "path": "hello_world.yml",
    "repo_name": "ansible-tower-samples",
    "repo_url": "https://github.com/ansible/ansible-tower-samples"
    }

8.2.6. Viewing the generated training data set

After content parser tool scans your Ansible files, it generates the training data set in an output subdirectory within your local directory. The training data set includes a ftdata.jsonl file, which is the main output of the content parser tool. The file is available in JSON Lines files format, where each line entry represents a JSON object. You must upload this JSONL file to IBM watsonx Code Assistant to create a custom model.

8.2.6.1. Structure of custom model training data set

The following is the file structure of an output subdirectory:

output/
  |-- ftdata.jsonl  # Training dataset 1
  |-- report.txt   # A human-readable report 2
  |
  |-- repository/ 3
  |     |-- (files copied from the source repository)
  |
  |-- metadata/ 4
        |-- (metadata files generated during the execution)

Where:

1
ftdata.jsonl: A training data set file, which is the main output of the content parser tool. The file is available in JSON Lines files format, where each line entry represents a JSON object. You must upload this JSONL file in IBM watsonx Code Assistant to create a custom model.
2
report.txt: A human-readable text file that provides a summary of all content parser tool executions.
3
repository: A directory that contains files from the source repository. Sometimes, ansible-lint updates the directory according to the configured rules, so the file contents of the output directory might differ from the source repository.
4
metadata: A directory that contains multiple metadata files that are generated during each content parser tool execution.
8.2.6.1.1. Using report.txt file to resolve ansible-lint rule violations

The report.txt file, that can be used to resolve ansible-lint rule violations, contains the following information:

  • File counts per type: A list of files according to their file types, such as playbooks, tasks, handlers, and jinja2.
  • List of Ansible files that were identified: A list of files identified by ansible-lint with a file name, a file type, and whether the file was excluded from further processing, or automatically fixed by ansible-lint.
  • List of Ansible modules found in tasks: A list of modules identified by ansible-lint with a module name, a module type, and whether the file was excluded from further processing, or automatically fixed by ansible-lint.
  • Issues found by ansible-lint: A list of issues along with a brief summary of ansible-lint execution results. If ansible-lint encounters files with syntax-check errors in the first execution, then ansible-runs initiates a second execution and excludes the files with errors from the scan. You can use this information to resolve ansible-lint rule violations.

8.2.7. Resolving ansible-lint rule violations

By default, the content parser tool uses ansible-lint rules to scan your Ansible files and ensure that the content adheres to Ansible best practices. If rule violations are found, the content parser tool excludes these files from the generated output. In such scenarios, it is recommended that you fix the files with rule violations before uploading the training data set to IBM watsonx Code Assistant.

By default, ansible-lint applies the rules that are configured in ansible-lint/src/ansiblelint/rules while scanning your Ansible files. For more information about ansible-lint rules, see the Ansible Lint documentation.

8.2.7.1. How does the content parser tool handle rule violations?

  • Using autofixes

    The content parser tool runs ansible-lint with the --fix=all option to perform autofixes, which can fix or simplify fixing issues identified by that rule.

    If ansible-lint identifies rule violations that have an associated autofix, it automatically fixes or simplifies the issues that violate the rules. If ansible-lint identifies rule violations that do not have an associated autofix, it reports these instances as rule violations which you must fix manually. For more information about autofixes, see Autofix in Ansible Lint Documentation.

  • Using syntax-checks

    Ansible-lint also performs syntax checks while scanning your Ansible files. If any syntax-check errors are found, ansible-lint stops processing the files. For more information about syntax-check errors, see syntax-check in Ansible Lint Documentation.

    The content parser tool handles syntax-check rule violations in the following manner:

    • If syntax-check errors are found in the first execution of ansible-lint, content parser tool generates a list of files that contain the rule violations.
    • If one or more syntax-check errors are found in the first execution of ansible-lint, the content parser tool runs ansible-lint again but excludes the files with syntax-check errors. After the scan is completed, the content parser tool generates a list of files that contain rule violations. The list includes all files that caused syntax-check errors as well as other rule violations. The content parser tool excludes files with rule violations in all future scans, and the final training data set does not include data from the excluded files.

Procedure

Use one of the following methods to resolve ansible-lint rule violations:

  • Run the content parser tool with the --no-exclude option If any rule violations, including syntax-check errors, are found, the execution is aborted with an error and no training data set is created.
  • Limit the set of rules that ansible-lint uses to scan your data with the --profile option

    It is recommended that you fix the files with rule violations. However, if you do not want to modify the source files, you can limit the set of rules that ansible-lint uses to scan your data. To limit the set of rules that ansible-lint uses to scan your data, specify the --profile option with a predefined profile (for example, minimum, basic, moderate, safety, shared, or production profiles) or by using ansible-lint configuration files. For more information, see the Ansible Lint documentation.

  • Run the content parser tool by skipping ansible-lint preprocessing You can run the content parser without ansible-lint preprocessing. The content parser tool generates a training data set without scanning for ansible-lint rule violations.

    To run content parser tool without ansible-lint preprocessing, execute the following command:
    $ ansible-content-parser source output -S

    Where:

    • source: Specifies the source of the training data set.
    • output: Specifies the output of the training data set.
    • -S or --skip-ansible-lint: Specifies to skip ansible-lint preprocessing while generating the training data set.

8.2.8. Merging multiple training data sets into a single file

For every execution, the content parser tool creates a training data set JSONL file named ftdata.jsonl that you upload to IBM watsonx Code Assistant for creating a custom model. If the content parser tool runs multiple times, multiple JSONL files are created. IBM watsonx Code Assistant supports a single JSONL file upload only; therefore, if you have multiple JSONL files, you must merge them into a single, concatenated file. You can also merge the multiple JSONL files that are generated in multiple subdirectories within a parent directory into a single file.

Procedure

  1. Using the command prompt, go to the parent directory.
  2. Run the following command to create a single, concatenated file:
    find . -name ftdata.json | xargs cat > concatenated.json
  3. Optional: Rename the concatenated file for easy identification.

You can now upload the merged JSONL file to IBM watsonx Code Assistant and create a custom model.

8.3. Create and deploy a custom model in IBM watsonx Code Assistant

After the content parser tool generates a custom model training data set, upload the JSONL file ftdata.jsonl to IBM watsonx Code Assistant and create a custom model for your organization.

Important

IBM watsonx Code Assistant might take a few hours to create a custom model, depending on the size of your training data set. You must continue monitoring the IBM Tuning Studio for the status of custom model creation.

For information about how to create and deploy a custom model in IBM watsonx Code Assistant, see the IBM watsonx Code Assistant documentation.

8.4. Configuring Red Hat Ansible Lightspeed to use custom models

After you create and deploy a custom model in IBM watsonx Code Assistant, you must configure Red Hat Ansible Lightspeed so that you can use the custom model for your organization.

You can specify one of the following configurations for using the custom model:

  • Enable access for all users in your organization

    You can configure the custom model as the default model for your organization. All users in your organization can use the custom model.

  • Enable access for select Ansible users in your organization

    Using the model-override setting, you can configure the custom model and make it available for select Ansible users only. For example, if you are using Red Hat Ansible Lightspeed both as an organization administrator and an end user, you can test the custom model for select Ansible users before making it available for all users in your organization.

8.4.1. Configuring the custom model for all Ansible users in your organization

You can configure the custom model as the default model for your organization, so that all users in your organization can use the custom model.

Procedure

  1. Log in to the Ansible Lightspeed with IBM watsonx Code Assistant Hybrid Cloud Console as an organization administrator.
  2. Specify the model ID of the custom model:

    1. Click Model Settings.
    2. Under Model ID, click Add Model ID. A screen to enter the Model ID is displayed.
    3. Enter the Model ID of the custom model.
    4. Optional: Click Test model ID to validate the model ID.
    5. Click Save.

8.4.2. Configuring the custom model for select Ansible users in your organization

Using the model-override setting in Ansible Visual Studio (VS) Code, you can configure the custom model and make it available for select Ansible users only. For example, If you are using Red Hat Ansible Lightspeed as both an organization administrator and an end user, you can test the custom model for select Ansible users before making it available for all users in your organization.

Procedure

  1. Log in to the VS Code application using your Red Hat account.
  2. From the Activity bar, click the Extensions icon Extensions .
  3. From the Installed Extensions list, select Ansible.
  4. From the Ansible extension page, click the Settings icon and select Extension Settings.
  5. From the list of settings, select Ansible Lightspeed.
  6. In the Model ID Override field, enter the model ID of the custom model.

    Your settings are automatically saved in VS Code, and you can now use the custom model.

Chapter 9. Viewing and managing Admin dashboard telemetry

Red Hat Ansible Lightspeed collects the following telemetry data by default:

  • Operational telemetry data

    This is the data that is required to operate and troubleshoot the Ansible Lightspeed service. For more information, refer the Enterprise Agreement. You cannot disable the collection of operational telemetry data.

  • Admin dashboard telemetry data

    This is the data that provides insight into how your organization users are using the Ansible Lightspeed service, and the metrics are displayed on the Admin dashboard. You can also disable the Admin dashboard telemetry if you no longer want to collect and monitor the telemetry data.

9.1. Prerequisites

To view and manage the Admin dashboard telemetry data, ensure that you have the following:

  • You have organization administrator privileges to a Red Hat Customer Portal organization with a valid Red Hat Ansible Automation Platform subscription.
  • You have installed the Ansible VS Code extension v2.13.148 that is required to collect Admin dashboard telemetry.
Important

Red Hat Ansible Lightspeed does not collect users' personal information, such as usernames or passwords. If any personal information is inadvertently received, the data is deleted. For more information about Red Hat Ansible Lightspeed’s privacy practices, see the Telemetry Data Collection Notice for the Admin dashboard.

9.2. What telemetry data is collected?

Following is the list of telemetry data that Red Hat Ansible Lightspeed collects:

  • Details of the organization that you are logged into, such as organization ID and account number
  • Large language models that you are connected to
  • Inline suggestions that were accepted, rejected, or ignored by your organization users
  • User sentiment feedback
  • Top 10 modules returned in code recommendations

9.3. Viewing the Admin dashboard telemetry

The Admin dashboard displays the analytics telemetry data that you can use to gain insight into how your organization users are using the Ansible Lightspeed service.

The Admin dashboard displays the following charts:

  • Inline suggestions accepted, rejected, or ignored by users

    This graph tracks the number of inline suggestions that were accepted, rejected, or ignored by users in your organization. Use this graph to gain insight into how your organization users are using the Ansible Lightspeed service.

  • User sentiment

    This graph measures the users' feedback (feelings, opinions). Use this graph to gain insight into the overall user experience with Red Hat Ansible Lightspeed.

  • Top 10 modules returned in code recommendations

    This graph displays the top 10 modules returned in code recommendations. Use this metric to determine which modules are being suggested the most to your organization’s automation developers.

Procedure

  1. Log in to the Ansible Lightspeed with IBM watsonx Code Assistant Hybrid Cloud Console as an organization administrator.
  2. From the navigation panel, select Ansible Lightspeed > Admin Dashboard.

    The Admin dashboard displays a graphical representation of analytics telemetry data for the last 30 days by default.

  3. Use the following filters to refine your telemetry data:

    • To view the telemetry data for a specific time period or for a custom date range, select the date range from the Quick Date Range list.
    • To view the telemetry data for a specific IBM watsonx Code Assistant model only, select the model ID from the Model Name list. By default, the Admin dashboard displays telemetry data for all models.

9.4. Disabling the Admin dashboard telemetry

Red Hat Ansible Lightspeed collects the Admin dashboard telemetry data by default. The data provides insight into how your organization users are using the Ansible Lightspeed service. If you no longer want to collect analytics telemetry data for your organization, you can disable the Admin dashboard telemetry.

After you disable the Admin dashboard telemetry, the Ansible Lightspeed service no longer collects the analytics telemetry data for your organization. The earlier telemetry data is still available on the Admin dashboard, but no latest data is displayed. If you re-enable the Admin dashboard telemetry, the Ansible Lightspeed service starts collecting data for your organization, and the metrics are displayed on the Admin dashboard after 24 hours.

Prerequisites

  • You have organization administrator privileges to a Red Hat Customer Portal organization with a valid Red Hat Ansible Automation Platform subscription.

Procedure

  1. Log in to the Ansible Lightspeed portal as an organization administrator.
  2. From the login screen, click Admin Portal.
  3. Under Admin Portal, click Telemetry.
  4. To disable the Admin dashboard telemetry, select Operational telemetry data only.

    Note

    To re-enable the Admin dashboard telemetry, select Admin dashboard telemetry data.

  5. Click Save.

Chapter 10. Troubleshooting

This section contains information to help you diagnose and resolve issues with using Red Hat Ansible Lightspeed with IBM watsonx Code Assistant.

10.1. Troubleshooting Red Hat Ansible Lightspeed configuration errors

10.1.1. Cannot access the Ansible Lightspeed administrator portal

The Ansible Lightspeed administrator portal can be accessed by the Red Hat organization administrator only.

If you are the Red Hat organization administrator, before you access the Ansible Lightspeed administrator portal, ensure that:

  • You have a valid Ansible Automation Platform subscription.

10.1.2. Cannot save the WCA key

When you enter the Watsonx Code Assistant (WCA) API key, authentication fails and shows the following error message:

IBM Cloud API key is invalid

Red Hat Ansible Lightspeed verifies the WCA API key by generating an associated access token. To resolve the error, ensure that you have not accidentally included any extra spaces when obtaining the WCA API key from IBM watsonx Code Assistant. If you still cannot upload the WCA key, contact IBM Support.

10.1.3. Cannot configure the model ID due to authentication failure

When you enter the model ID in the Red Hat Ansible Lightspeed administrator portal, the authentication fails.

To resolve the error, ensure that:

  • You have configured a valid WCA API key before you upload the model ID.
  • You have not accidentally included any extra spaces when entering the model ID.

10.1.4. Cannot configure the model ID due to inference failure

While validating the model ID, Red Hat Ansible Lightspeed performs a test inference. If Red Hat Ansible Lightspeed detects an error, the validation fails and an Inference failed message is displayed.

To resolve the error, ensure that:

  • You have a valid WCA API key and model ID.
  • You have not accidentally included any extra spaces when obtaining the WCA key and model ID from IBM watsonx Code Assistant.

10.2. Troubleshooting Ansible Visual Studio Code extension errors

10.2.1. Cannot view the generated code recommendations using the Ansible VS Code extension

The following scenarios are possible:

  • You receive a 403 error message.

    To resolve this error, ensure that:

    • Your organization administrator has configured Red Hat Ansible Lightspeed for your organization.
    • You are part of an organization that has a trial or paid subscription to both Ansible Automation Platform and IBM watsonx Code Assistant.
  • You have not configured the required Ansible VS code extension settings.

  • You receive a Failure on completion requests error when you make inference requests in VS Code.

    If you are part of an organization that has a trial or paid subscription to both Ansible Automation Platform and IBM watsonx Code Assistant, but your organization administrator has not configured an IBM watsonx Code Assistant model for your organization, you will encounter a Failure on completion requests error when you make inference requests in VS Code.

  • Your VS Code Workspace settings override user settings.

    If your Workspace settings are configured, they can override our user settings even if you have configured the Ansible VS Code extension correctly. The Workspace settings can disable your VS Code extension settings, and therefore you cannot access the Ansible Lightspeed service.

    To resolve this error, ensure that there are no Workspace settings configured in VS Code. For more information, see Workspace settings in the VS Code documentation.

  • You entered a multitask prompt, but code recommendations were not generated.

    To resolve this error, log out of VS Code and log in again using your Red Hat account.

  • You clicked a different location or switched to a different window; therefore, the populated code recommendations disappeared.

    The Red Hat Ansible Lightspeed service could take multiple seconds per task to populate the code recommendations. If you are using a multitask prompt, the Red Hat Ansible Lightspeed service takes a bit longer to populate the results. Do not move your cursor or press any key while the code recommendation is being generated. If you change the cursor location or press any key, the Ansible VS Code extension cancels the request and the Red Hat Ansible Lightspeed service does not process your request. In this scenario, you must get the cursor back to its original position and repopulate the results.

10.2.2. Cannot request code recommendations by using the Ansible VS Code extension

The following error message is displayed:
Your trial to the generative AI model has expired. Refer to your IBM Cloud Account to re-enable access to the IBM watsonx Code Assistant.

To resolve this error, refer to your IBM Cloud account and select an upgrade option.

10.3. Troubleshooting Ansible code bot errors

10.3.1. Cannot access Ansible code bot

After you install Ansible code bot and attempt to log in, you receive the following error message:

Your organization does not have a valid Red Hat Ansible Lightspeed subscription

After you install Ansible code bot, you are redirected to a page that shows an active subscription status, as shown in the following image:

Figure 10.1. Ansible code bot login screen with an active subscription

Ansible code bot login screen with an active subscription

If the login screen displays an inactive subscription status, Ansible code bot does not scan your Git repositories. The error occurs because your organization does not have a valid Ansible Automation Platform subscription. To resolve this error, ensure that you are part of an organization that has a valid Red Hat Ansible Automation Platform subscription.

10.3.2. Cannot scan your Git repository using Ansible code bot

If the Ansible code bot is not configured correctly, it does not scan your Git repositories or does not create pull requests.

To resolve Ansible code bot errors, ensure that:

  • You have selected all the Git repositories that you want to scan.
  • You have a .yml configuration file named ansible-code-bot.yml in your repository .github folder. For example, .github/ansible-code-bot.yml.

Run a manual scan on your git repositories by adding the ansible-code-bot-scan topic to your repository. For more information, see Manually scan your Git repositories.

If the Ansible code bot still cannot scan your Git repository, the following scenarios are possible:

  • The Ansible code bot did not identify any ansible-lint violations in the Git repository.
  • The Ansible code bot does not have permission to scan the Git repository.
  • Your organization does not have a valid Red Hat Ansible Automation Platform subscription.

10.3.3. Cannot create pull requests

You might encounter an error where the Ansible code bot cannot create pull requests after scanning your Git repositories.

To resolve this error, ensure that:

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.