OBS ACL Feature documentation

This MR aims to document the OBS ACL feature implemented in-house. For more details, please see task AT5645. https://phabricator.apertis.org/T5645

Signed-off-by: Ritesh Raj Sarraf ritesh.sarraf@collabora.com

content/guides/obs-acl-feature.md

++++
+title = "OBS Access Control List Feature"
+weight = 100
+date = "2021-05-20"
++++
+
+This document outlines the OBS ACL feature that has been implemented on the Collabora instance of OBS. For a detailed background on the implementation, please see task [AT5645](https://phabricator.apertis.org/T5645)
+
+
+# Background
+As an Apertis maintainer, i need to support creation of different projects in OBS for multiple product teams and restricting the access to only for developers of the product.
+
+# Usecase
+For a product team PT, we need to hide all PT related projects (pt:target, pt:development. pt:sdk) from other teams, with only PT team should be allowed to see and use this projects.
+
+These instructions are used in the project configuration to hide the projects from others, but the issue is that hidden project cannot be used as a dependencies in any other pt:* projects:
+`<sourceaccess> <disable/> </sourceaccess>  <access> <disable/> </access>`
+
+# Requirements
+The selected OBS projects should be visible only to their project teams
+* Only explicitly selected people/groups see any information about the selected OBS projects
+* Restricted projects should able to be used as dependencies by other projects without necessarily sharing their sources but only sharing the binaries
+* Sources aren't leaked out to other teams
+* Binaries aren't leaked out to other teams
+* Published APT repositories for resulting packages are protected as well
+
+# OBS ACL Feature Implementation
+
+The OBS ACL feature has the following behaviour:
+
+* A hidden project is one with `<access>` set to `disabled`
+* Build dependencies are via `<path project="…" repository="…"/>` elements in a `<repository>` section
+* Any hidden project can use any other hidden project as a build dependency
+* A user who views meta config with a `<path …` to a project they cannot see, will see `<path project="HIDDEN" …>`
+* Said user SHOULD NOT save that meta config but this is not enforced
+* a non-hidden project can still depend on a hidden one, but
+  * the hidden project must whitelist the non-hidden one
+  * this is done with an `<allowbuilddep name="name:of:public:project"/>` element in the meta config
+  * this element is contained directly in the `<project …>` section, ie the same level as the `<title …>`
+
+# Example demonstration
+In the below example OBS projects, we demonstrate the **OBS ACL** feature.
+
+We have 4 repositories, as listed below: 
+
+* home:ritesh:apertis:demo:base-repo-hidden
+* home:ritesh:apertis:demo:app-repo-hidden
+* home:ritesh:apertis:demo:app-repo-public
+* home:ritesh:apertis:demo:app-repo-allow-build-dep
+
+
+wherein `base-repo-hidden` is the base hidden repository, to which no public repositories will have access to by default.
+
+Then, we have `app-repo-hidden` repository, which is a hidden repository, and thus will have access to the `base-repo-hidden` repository.
+
+Next, we have `app-repo-public`, which is a public repository, and thus will not have access to the `base-repo-hidden` repository.
+
+And finally, we have `app-repo-allow-build-dep`, which is also a public repository, and thus will not have access to the `base-repo-hidden` repository. The `app-repo-allow-build-dep` repository is marked as an exception through the `<allowbuilddep ....>` attribute in the meta configuration for `base-repo-hidden` repository, thus granting it access to the `base-repo-hidden` repository.
+
+
+## home:ritesh:apertis:demo:base-repo-hidden
+This is the base OBS repository. This repository houses our private package (in this example, `debhelper`) which will be used by packages in other repositories as their build dependency
+
+{{< figure src="/images/base_repo_meta_conf.png" alt="Base repository Private" title="Base repository Private" >}}
+{{< figure src="/images/base_repo_overview.png" alt="Base repository Private overview" title="Base repository Private overview" >}}
+
+## home:ritesh:apertis:demo:app-repo-hidden
+This is an example OBS repository which houses an application. This repository is also set as a private repository. Thus this repository will have access to packages from the base repository, which in this case would mean: `usrmerge => debhelper`. This is because a private repository can access the contents of another private repository.
+
+{{< figure src="/images/app_repo_hidden_meta_conf.png" alt="App repository Private" title="App repository Private" >}}
+{{< figure src="/images/app_repo_hidden_overview.png" alt="App repository Private overview" title="App repository Private overview" >}}
+
+## home:ritesh:apertis:demo:app-repo-public
+This is an example OBS repository which houses an application. This repository is set as a public repository. Thus this repository will not have access to packages from the base repository, which in this case would mean: `usrmerge ≠> debhelper`.  This is because a public repository cannot access the contents of a private repository.
+
+{{< figure src="/images/app_repo_public_meta_conf.png" alt="App repository Public" title="App repository Public" >}}
+{{< figure src="/images/app_repo_public_overview.png" alt="App repository Public overview" title="App repository Public overview" >}}
+
+## home:ritesh:apertis:demo:app-repo-allow-build-dep
+This is an example OBS repository which houses an application. This repository is set as public repository. This, by default, this repository will not have access to packages from the base repository. But, for this repository, we well add an access control into the base repository, to allow it access to packages from the base repository. Thus, it would result in: `usrmerge => debhelper`
+
+{{< figure src="/images/app_repo_public_allowBuildDep_meta_conf.png" alt="App repository allowBuildDep" title="App repository allowBuildDep" >}}
+{{< figure src="/images/base_repo_allowBuildDep_meta.png" alt="Base repository allowbuilddep" title="Base repository allowbuilddep" >}}
+
+{{< figure src="/images/app_repo_allowBuildDep_overview.png" alt="App repository Public (with allowbuilddep) overview" title="App repository Public (with allowbuilddep) overview" >}}
+
+# Limitations
+There are some limitations in the OBS ACL feature implementation, which are mentioned below
+
+* Nested ACL dependencies: Nested ACL dependencies, wherein repo A depends on repo B and vice-versa.  Project C, which is a public repostiory with an `<allowbuilddep ...>` attribute, will need to be mentioned in all parent repositories along with their nested dependency repositories. In this case, the `<allowbuilddep ...>` attribute will have to be added to both repo A and repo B. Incorrect definition of ACL rules, especially like this example of nested rules, reflect with an error message like below
+
+{{< figure src="/images/app_repo_nested_broken.png" alt="Broken ACL setup" title="Broken ACL setup" >}}

[Martyn Welch]

Don't provide links to tasks - very few people have access to those. Explain the context here to avoid the need to go look elsewhere.

[Ritesh Raj Sarraf]

Yes. I mean that was my thought to just have a link. So that, people who need more information, should be able to access it through the task. Others, who shouldn't have a detailed view, will not be allowed by Phabricator.

[Martyn Welch]

If we're going to mention specific product teams (especially when we are using acronyms), I really think this needs to be in the private designs. Which is also generated using Hugo, so moving it is trivial...

[Ritesh Raj Sarraf]

I thought of this and felt PT was generic enough as a Product Team There were references to Guradian Project, which I removed to ensure no names are provided. But, it looks like, PT is a name in itself within Bosch.

But I only interpreted it as an acronym for Product Team

[Martyn Welch]

I'm quite interested to see how these get formatted. The pure Markdown way would be:

![App repository Private](/images/app_repo_hidden_meta_conf.png)

Though that's not rendering the alt text at the moment and doesn't actually add a title to the image that this would appear to do.