Add task docs for ansible

[captncraig]

Completes #5959

[clayton-cornell]

Some suggestions and questions

[clayton-cornell]

Suggested change

	baseurl: "https://packages.grafana.com/oss/rpm"
	enabled: true
	gpgkey: "https://packages.grafana.com/gpg.key"
	baseurl: "https://rpm.grafana.com/oss/rpm"
	enabled: true
	gpgkey: "https://rpm.grafana.com/gpg.key"

The info documented here: https://packages.grafana.com/ shows baseurl=https://rpm.grafana.com Does Ansible work with the deeper dir structure or does it need/work with the root URL?

Same path documented for gpgkey Just changing for consistency in all sources... https://packages.grafana.com/ and https://rpm.grafana.com/ and https://grafana.com/docs/agent/latest/flow/setup/install/linux/

[thampiotr]

LGTM with Clayton's suggestions. Thanks!

[thampiotr]

I think we should link to https://grafana.com/docs/agent/next/flow/get-started/run/linux/ as "Run".

[ishanjainn]

Have you checked grafana-ansible-collection repo. We do have built roles for installation of agent already(and it supports Flow mode too)

I'd like to avoid recommending anything different than what we already are as that just makes things complex tbh

[ishanjainn]

https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/ansible/ansible-grafana-agent-linux/

Here's the link to the doc. And configuration might look long but thats just the agent config. If you want it to be small, You just have to remote that section but still you would need the agent config in the host so you would add a seperate task. Both cases work by ansible users generally prefer to keep tasks aligned to a single tasks, Hence the role. Lemme know of you have any questions.

[thampiotr]

I think that there are some potential issues with agent using grafana-ansible-collection:

• It is built for both static mode and Flow. These docs in this PR must be only for Flow. Because the ansible role supports both, its configuration is quite complex. Would be better (and more future-proof when we switch to Flow) to have flow-only role.
• It seems that grafana-ansible-collection requires an extra step to install the collection, which pulls a bunch of other roles, which are Grafana Cloud specific. Agent is vendor-neutral, so it may be better to let users install just the agent role. Is that possible?
• How is grafana-ansible-collection supported? What is the policy for breaking changes to it? We wanted to provide something very simple that comes in the same 'package' with the agent, which we can support fully. The setup we have here is a few lines of YAML and we (agent maintainers) would have capacity to support it.
• Would grafana-ansible-collection work for most Ansible users? Or are there different setups where users would end up writing their own roles anyway? It's better to have a basic setup example for those who want to DIY their agent role to fit their organisation.

Having said that, I don't mind at all to advertise, link to, and recommend the grafana-ansible-collection for Agent users who are looking for a more sophisticated and complete solution. But I think there's a good value for us to keep this simple "Agent with Ansible 101".

[ishanjainn]

Hey thanks, Just a few of my takes.

It is built for both static mode and Flow. These docs in this PR must be only for Flow. Because the ansible role supports both, its configuration is quite complex. Would be better (and more future-proof when we switch to Flow) to have flow-only role.

Hey, KInda disagree here. Configuration is the list of available variables that users can use but the simplest 101 which you are trying is very small see(smaller than the playbook here tbh). And for flow, The configuration is

- hosts: all
  tasks:
    - name: Install Grafana Agent
      ansible.builtin.include_role:
        name: grafana.grafana.grafana_agent
      vars:
        grafana_agent_mode: flow
        # Change config file on the host to .river
        grafana_agent_config_filename: config.river
        # Change config file to be copied
        grafana_agent_provisioned_config_file:  "files/config.river"
        # Remove default flags
        grafana_agent_flags_extra:
          server.http.listen-addr: '0.0.0.0:12345'

Personally I dont see anything simpler than this,
And as for flow only role, Thats just duplication of a lot of things just to change a couple of commands, Hence that might be not possible and agent when does remove static, It would be removed from here aswell so we should have no issues

It seems that grafana-ansible-collection requires an extra step to install the collection, which pulls a bunch of other roles, which are Grafana Cloud specific. Agent is vendor-neutral, so it may be better to let users install just the agent role. Is that possible?

Nope, No installation is necessary for the collection. The collection is baked into ansible binary so if you are using ansible, you already have our collection installed so no extra steps.

How is grafana-ansible-collection supported? What is the policy for breaking changes to it? We wanted to provide something very simple that comes in the same 'package' with the agent, which we can support fully. The setup we have here is a few lines of YAML and we (agent maintainers) would have capacity to support it.

I actively maintain it so this shouldn't be a worry, but yeah the community helps too a lot!

Would grafana-ansible-collection work for most Ansible users? Or are there different setups where users would end up writing their own roles anyway? It's better to have a basic setup example for those who want to DIY their agent role to fit their organisation.

Yes, Users are free to customize, which is why you see so many available role variables. But since you are doing a 101, This shouldn't be a concern

Having said that, I don't mind at all to advertise, link to, and recommend the grafana-ansible-collection for Agent users who are looking for a more sophisticated and complete solution. But I think there's a good value for us to keep this simple "Agent with Ansible 101".

Thanks and yeah sure but IMO i don't get why we should do a playbook way when we already have roles built for it.

Just some opinions and what I feel as I actually have been an ansible user for sometime so just trying to mention what general ansible users would prefer/and what we should be recommending.

[thampiotr]

Thanks @ishanjainn for sharing this, much appreciated!

Hence that might be not possible and agent when does remove static, It would be removed from here aswell so we should have no issues

At some point we will remove the static mode from the latest versions of the Agent Flow, but there still will be users that didn't migrate and are on static mode. Both groups of users may use Ansible, so I wonder if grafana-ansible-collection can remove support for static mode, but still keep the older versions of the collection available for those that didn't migrate?

Similarly, I wonder what is your breaking changes policy?

Nope, No installation is necessary for the collection.

Thanks for confirming! I would expect to see agent role over here, but it's not there? Could you point me at the right place?

Also, @captncraig, when you're back, I wonder what do you think is the best option forward?

[ishanjainn]

Both groups of users may use Ansible, so I wonder if grafana-ansible-collection can remove support for static mode, but still keep the older versions of the collection available for those that didn't migrate?

Yeah that can be done, Whenever we do that and just keep flow mode in latest versions we can just ket users know if they are using static mode they would have to use a specific version of the collection.

For breaking changes we haven't had a scenario yet where a breaking change in agent breaks the role as the role is just a wrapper around the binary and config (where the chnages are), At max its small fields we add to the role variables but that alaways kept in alignment with agent releases.

[captncraig]

If that is what we are recommending in grafana cloud, we should do the same here for consistency. Part of the original idea was to have something simple and standalone, but the snippet in that doc is really nice. If that doc was for flow mode, I would absolutely say this page is redundant, and we should use the same one.

Perhaps I should make a copy of https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/ansible/ansible-grafana-agent-linux/ that uses flow mode? Can include it in our docs for now, and then reference or use it in the grafana-cloud docs as we decide to publish that as the default version.

[ishanjainn]

@captncraig, I'll be adding the flow mode instructions to the cloud doc by this week itself(its been long due), Then probably you can use the doc as is. Hope that helps!

[captncraig]

Ok, I'm going to close this, with intention of copying your doc in once completed. @ishanjainn can you please update #5959 when that new flow doc is ready?

[ishanjainn]

Yup will do!
Fo reference, The PR to update the ansible doc in cloud docs https://github.com/grafana/website/pull/17894 if you wanna have a look