RFC: Github Profile for Foreman and Katello

[Dirk]

Yesterday we discussed many different topics after the Birthday Event. One that came up was user barriers and one I identified was the Github landing page(s).

Github has a feature for a while called Organization profile READMEs

An example can be found at Pulp · GitHub

I would put this on my agenda if noone is already working on this. And I already have the go to utilize our marketing team including graphic design, so it may take longer but give me a better result.

So now my question what to add? My idea for Foreman would be:

• description of the project
• a new version of the picture of the architecture (to get rid of https://theforeman.org/static/images/foreman_architecture.png)
• link to https://projects.theforeman.org/ and a list of projects using it instead of github
• links to community and documentation
• link to the plugin overview and an explanation that not all plugins are hosted at this organization
• links to professional services, trainings and downstream products

For Katello I would do similar, but of course we need another picture and some links will differ.

[ekohl]

@Dirk

For Katello I would do similar, but of course we need another picture and some links will differ.

Not something I’ve discussed publicly, but I’ve also suggested to some people to move all git repos from Katello into theforeman. These days there are not that many repos and it simplifies management.

[Dirk]

I would not call it my Xmas present, but we have finally found some time. What do you think of this text for the Github profile? I used the text from the homepage but added to it where needed. Marketing convinced my to go not to deep into details.

---

Description

Foreman is a complete lifecycle management tool for physical and virtual servers. We give system administrators the power to easily automate repetitive tasks, quickly deploy applications, and proactively manage servers, on-premise or in the cloud.

Features

Provisioning

Provision on bare-metal (MaaS) & public or private clouds all from one place with one simple process.

Configuration

A complete configuration management solution including an ENC for Puppet and Salt, built-in support for parameterized classes and hierarchical parameter storage. Or integrate Ansible by assigning roles and variables.

Monitoring

Collect Puppet, Salt, and Ansible reports and facts. Monitor host configuration, report status, distribution, and trends.

Orchestration

Utilize Scripts or Ansible playbooks for remote execution or pull them using MQTT.

Content Management

To mirror and stage content like RPM and DEB packages, Container images, or any type of file have a look at Katello, a fixed set of plugins for Foreman.

With a wide range of plugins, you can add even more features, not all of them can be found at this organization, so have a look at the plugin overview.

Issue tracking

Not all parts of the project track issues here at GitHub! So, if you are missing the issues here, check out the issue tracker.

Getting help

For getting easily started check out the documentation and the Community support. There are also regular demos on the YouTube channel.

There is also an overview of trainings provided by other companies.

If you prefer assistance, benefit by companies providing professional services or even consider one of the downstream products: Red Hat Network Satellite or orcharhino.

---

They also convinced me to use only a header graphic for the profile. So any preference?

I like number 4 as the solid background is a bit boring and putting the hard hat on the logo looks nice, but not sure about it so 5 is perhaps better.

Header

• Number 1 (Solid background, Hard Hat on top)
• Number 2 (Solid background, Hard Hat over the top)
• Number 3 (Solid background, Hard Hat on left)
• Number 4 (Non-solid background, Hard Hat on top)
• Number 5 (Non-solid background, Hard Hat over the top)
• Number 6 (Non-solid background, Hard Hat on left)

Still I wanted a new version of the architecture graphic. My idea was to reduce the details and if you like the style than add additional ones going into detail for each feature. Any opinions on this?

My plan would be collecting feedback here, adjust where needed and then create the pull request so they can hopefully be merged in time to show this on cfgmgmtcamp.

[ekohl]

@Dirk

I would not call it my Xmas present, but we have finally found some time. What do you think of this text for the Github profile? I used the text from the homepage but added to it where needed. Marketing convinced my to go not to deep into details.

Maybe it’s lost in the markup, but I suspect you intend the features to be headers. Other than that I think it’s a great start.

@Dirk

They also convinced me to use only a header graphic for the profile. So any preference?

We only have them side by side in foreman-graphics/logo at master · theforeman/foreman-graphics · GitHub so I never considered it on top. That’s why I voted for option 6.

@Dirk

Still I wanted a new version of the architecture graphic. My idea was to reduce the details and if you like the style than add additional ones going into detail for each feature. Any opinions on this?

I like the simplification.

Technically the CLI goes through the API. Should we change that to be CLI → API → Foreman. And then also mention Ansible → API → Foreman.

I’d also suggest to add TFTP for the Smart Proxy, since it goes together with DNS & DHCP for provisioning. I can also understand leaving it out, since you don’t want to draw the complete diagram.

[Dirk]

@ekohl

Maybe it’s lost in the markup, but I suspect you intend the features to be headers. Other than that I think it’s a great start.

Yes, correct, somewhere lost between different formats.

@ekohl

I like the simplification.

Technically the CLI goes through the API. Should we change that to be CLI → API → Foreman. And then also mention Ansible → API → Foreman.

I’d also suggest to add TFTP for the Smart Proxy, since it goes together with DNS & DHCP for provisioning. I can also understand leaving it out, since you don’t want to draw the complete diagram.

I would avoid the extra layer. It is technically correct for sure, but does it matter to the user? I think no and it makes understand the options not easier. Adding Ansible directly would work, but should we name a specific product again or use a generic term like Config Management or Orchestration then? I would prefer keeping specific things to some detail graphics.

I was asked to limit it to the four most important ones. As I argued that it is important to show there are many options I was limited to three and I did not want to limit it to provisioning. But I am totally open for a different selection.

[ekohl]

@Dirk

Adding Ansible directly would work, but should we name a specific product again or use a generic term like Config Management or Orchestration then? I would prefer keeping specific things to some detail graphics.

It’s mostly because we provide a supported foreman-ansible-modules collection to manage Foreman itself. We don’t have such a thing for Puppet (though there are third party implementations floating around).

But I can see how that can be confusing in such a diagram.

[Dirk]

Created the Pull request for the profile at Add Github profile by dgoetz · Pull Request #2 · theforeman/.github · GitHub

As a next step I will create some mockups for the features to get similar graphics like the one for architecture from our graphic designer. When I have them all ready I will ask here for feedback again before doing a Pull request on the Foreman graphics repository. Afterwards we can use them on the homepage and in docs.

[Dirk]

So for the next round of feedback I have pictures of the workflow of the most important features similar to the simplified architecture graphic. The biggest difference is that lines are labeled, where I was told to try it with one or two words, so it is in most cases the data which are send, sometimes it is a verb. I wanted the feature added to the graphic so it can stand alone, but because of the simplified nature it is more meant to be used with some explanation.

So let’s start mit Provisioning:

I took an example with a compute resource, so it shows how it would work with Libvirt or VMware when you use PXE and also manage DNS. I thought this would be a good example to show the capabilities. If other workflows should be drawn to like physical servers, discovery, bootdisk on VMware, … (Typo in Installation Media already noted)

Next Configuration Management:

I decided to go here with two images as it is normally only one and it allows to a more simple design. So to differentiate the used solution was added to the title. Optional components use dotted lines.

Next Orchestration:

Here I thought both flows (push and pull) could exist in one graphic so you easily see the difference.

Monitoring:

A very simplified one not going into detail on any other feature just showing some sending data directly and others via Smart Proxy.

And last but not least, the most complicated one Content Management:

I think it shows all important components and details, perhaps even to much. I am not hundert percent happy with having the SUSE logo for SCC Manager and having no Red Hat logo on it, but I have no good idea to solve this without making it even more complex.
Additional question: Are the logos (Katello, Pulp, Candlepin) available somewhere as vector graphics?

Please tell me what you think about the graphics, what additional ones are needed (perhaps if you can with a mock-up), anything else coming to your mind!

Plan is to incorporate feedback and then add them to the graphics repository in the source format, svg and png, so they can easily be used. Then start to do some pull request to integrate them on the website, documentation, …

[ekohl]

I use dark mode and then the transparent background with black lines ends up being black on gray, which is hard to read. I don’t know how it would look on GitHub, but here in Discourse it’s hard. Anything that could be done about that?

[Dirk]

As far as I know only by exporting it with white background not sure if this will look good on dark mode or inverting the colors and the having a light and dark version. But I will ask our graphics designer if she has another idea.

Currently graphics in the documentation are with white background, so I exported one in this way.

[ekohl]

@Dirk

So let’s start mit Provisioning:

(Virtual) Maschine → Machine

@Dirk

I took an example with a compute resource, so it shows how it would work with Libvirt or VMware when you use PXE and also manage DNS. I thought this would be a good example to show the capabilities. If other workflows should be drawn to like physical servers, discovery, bootdisk on VMware, … (Typo in Installation Media already noted)

We also have HTTPBoot, which replaces TFTP.

I know @docs also struggles with capturing all these flows, so I think just the profile shouldn’t lay out all the options in the profile.

@Dirk

Next Configuration Management:

I think “Server” is a bit ambiguous. Perhaps make it Puppetserver? Always a bit hesitant with using branding, but would the Puppet logo make sense here?

@Dirk

And last but not least, the most complicated one Content Management:

Certainly the most complicated one, and I’ll ask @katello to weigh in here.

One thing to note is that communication to Candlepin always goes through Foreman. So it’s:

Host → Foreman (/ Katello) → Candlepin

In case there’s host isolation it’s even:

Host → Content Proxy (Apache) → Foreman → Candlepin

Perhaps the whole diagram is easier if you take a content example without host isolation and then a separate example with host isolation.

As for SCC Manager: I’ve never used it, so perhaps this is like PuppetDB and it should be dashed lines to indicate it’s optional.

[Dirk]

@ekohl

(Virtual) Maschine → Machine

Good catch, a typical German - English error!

@ekohl

We also have HTTPBoot, which replaces TFTP.

So how you what add it? Simply change “TFTP” to “TFTP / HTTPBoot” or is more change needed?

@ekohl

I think “Server” is a bit ambiguous. Perhaps make it Puppetserver? Always a bit hesitant with using branding, but would the Puppet logo make sense here?

My initial idea was only the icon and than Puppetserver written as a word because of there is the other component PuppetDB, too. Would this be better or would you prefer simply using the logo and not adding the server?

@ekohl

Candlepin always goes through Foreman

I also noted this is the only line without a note. So would it be correct to draw a line from the Host to Foreman marked as “Subscription” and then change “manages” on the line from Foreman to Candlepin also to “Subscription” or perhaps the plural here?

@ekohl

host isolation

I would leave this out for now to make it not more complex.

@ekohl

SCC Manager … dashed lines

Good catch, will get this changed.

[ekohl]

@Dirk

So how you what add it? Simply change “TFTP” to “TFTP / HTTPBoot” or is more change needed?

I think that’s actually simple enough. On an abstract level they’re interchangeable.

@Dirk

My initial idea was only the icon and than Puppetserver written as a word because of there is the other component PuppetDB, too. Would this be better or would you prefer simply using the logo and not adding the server?

I was thinking both Puppetserver and the logo, similar to how Ansible has both the logo and the name.

@Dirk

I also noted this is the only line without a note. So would it be correct to draw a line from the Host to Foreman marked as “Subscription” and then change “manages” on the line from Foreman to Candlepin also to “Subscription” or perhaps the plural here?

Yes, Host → Foreman with the subscription label would be correct. Then Foreman → Candlepin with subscriptions (plural) is a good start. If anyone can come up with better labels, they’re welcome to improve it.

@Dirk

I would leave this out for now to make it not more complex.

Perhaps mention it with text and refer to docs on the topic.

[Dirk]

@Dirk

light and dark version

While your graphics designer feared the logos will not work well on a dark background, she was quite happy with the dark version after trying. So it could look like this if we can utilize a light and a dark version:

(Was created before we adjusted the lines)

@ekohl

Puppetserver and the logo

I personally think the Puppet logo and Puppetserver is redundant, with the icon I think we should write Puppetserver next to it instead of below. So perhaps we should use only the logo and don’t care about the detail that it is the Puppetserver? I just wanted to have it as also the PuppetDB is in the graphic.

I would wait for more feedback before uploading all the graphics again which all got already adjusted but she is working on cleaning them up at the moment, too.

[jeremylenz]

@ekohl

One thing to note is that communication to Candlepin always goes through Foreman. So it’s:

Host → Foreman (/ Katello) → Candlepin

In case there’s host isolation it’s even:

Host → Content Proxy (Apache) → Foreman → Candlepin

This looks correct to me! A host’s RHSM configuration always points to Foreman (or a smart proxy), not to Candlepin directly. And then we forward those requests through to Candlepin via Katello’s candlepin proxies controller.

[Dirk]

Just to encourage the usage of the images already in the upcoming conferences, even if we won’t finish it in time, they will be part of the Foreman-Graphics repository so Creative Commons Attribution-ShareAlike 3.0 Unported License will apply!

I will do a pull request this week if nothing goes wrong!

[ekohl]

I’ve at least merged the basic PR and The Foreman · GitHub now shows that.

[Dirk]

It is not the Friday before the conferences as I did not find the time earlier, but now the promised PR to foreman-graphics is here: Add images for Github Profile and Documentation by dgoetz · Pull Request #5 · theforeman/foreman-graphics · GitHub

And as I really want the old architecture image to be replaced, I directly create also Replace the archtitecture image with a newer one by dgoetz · Pull Request #2126 · theforeman/theforeman.org · GitHub

So I would leave adding the feature images to the documentation to @docs as they will know best.

And as we postponed this until now the question is should we generate also a Github profile for Katello in the same style?

[ekohl]

@Dirk

And as we postponed this until now the question is should we generate also a Github profile for Katello in the same style?

I’m still leaning to moving everything from Katello to theforeman and leave the old organization as a redirect to theforeman.

[Dirk]

I would prefer this, too. Not only because it will mean no additional work, but nowadays the reality is that it is already one project instead of two and it will make things easier everywhere.

Then I would leave it as it is and if we see no progress on this in the near future we still can come back to it and create a profile.