Update documentation WRT to recent $platform changes

[pat-s]

I am unsure if the following when: syntax is also deprecated and should be updated:

when:
  - platform: linux/amd64

@qwerty287 Do you know more here?

---

fix #2505

[woodpecker-bot]

Deploying preview to https://woodpecker-ci-woodpecker-pr-2531.surge.sh

[qwerty287]

Do you know more here?

I need to check the code again.

The syntax was not deprecated though, so it still should work - but I don't know what it should do

[qwerty287]

OK, then when: platform isn't deprecated, it is still there. However, you can/should only use it on steps so you can define steps that are only executed on specific archs.

[qwerty287]

So from my side this looks good.

I can't realy say anything about kubernetes though, I don't use it (and never used it). Maybe someone else with note experience can check it again?

[pat-s]

Maybe @zc-devs?

[zc-devs]

Wait a little bit, I'll explain more precisely later.

[zc-devs]

I've not used matrix and architecture builds. All that I'll say below is based on documentation, experiments, common sense and my expectations :)

---

First of all, let's work out what is the Matrix workflows and how they work. Consider next example:

matrix:
  OS:
    - linux
    - windows
  ARCH:
    - x86
    - arm

steps:
  build:
    image: alpine
    commands:
      - echo "This is a build for ${OS} operating system and ${ARCH} processor architecture"

Matrix - is just set of various variables combinations. And workflow is just a template. Example becomes 4 workflows after interpolation:

steps:
  build:
    image: alpine
    commands:
      - echo "This is a build for linux operating system and x86 processor architecture"

steps:
  build:
    image: alpine
    commands:
      - echo "This is a build for linux operating system and arm processor architecture"

steps:
  build:
    image: alpine
    commands:
      - echo "This is a build for windows operating system and x86 processor architecture"

steps:
  build:
    image: alpine
    commands:
      - echo "This is a build for windows operating system and arm processor architecture"

These workflows are scheduled to run.

---

Next, let's look at labels. I can hardly add anything, it is clear enough. Note that each Agent have platform=agent-os/agent-arch label.

If we look at next paragraph, we'll see example of pipeline distribution by labels.

---

Assume, we have 2 Agents: one on linux/arm and one on windows/amd64. And next workflow definition:

matrix:
  PLATFORM:
    - linux/arm
    - windows/amd64

steps:
  build:
    image: golang:${PLATFORM}
    commands:
      - go build

It interpolates into 2 workflows:

steps:
  build:
    image: golang:linux/arm
    commands:
      - go build

steps:
  build:
    image: golang:windows/amd64
    commands:
      - go build

They would be run randomly on Agents, because we didn't set any label.

If you add:

labels:
  location: mordor

then they won't run at all, because there is no Agent in Mordor (with label location=mordor) :)

Let's see what if you add standard platform label:

matrix:
  PLATFORM:
    - linux/arm
    - windows/amd64

labels:
  platform: ${PLATFORM}

steps:
  build:
    image: golang:${PLATFORM}
    commands:
      - go build

Then we'll have 2 pipelines:

labels:
  platform: linux/arm

steps:
  build:
    image: golang:linux/arm
    commands:
      - go build

labels:
  platform: windows/amd64

steps:
  build:
    image: golang:windows/amd64
    commands:
      - go build

They will be scheduled each one on dedicated Agent:

That is how it works on backends, other than Kubernetes. This is labels approach. It should work in Kubernetes too:

This looks more canonical to me (from Woodpecker perspective) and should be used in general.

---

What's about nodeSelector?

I think nodeSelector in Kubernetes is similar to label in Woodpecker, but exists in Kube only. It contains platform by default like labels.

So, pipelines distribution/scheduling by platfrom should work out-the box via labels. We can also use labels and node selector to schedule workflows (entirely) more precisely, by location, for example. In that case labels approach is prefferable, probably, too. Althogh, in Kube backend taints may be better than nodeSelector. Arguable...

What doess node selector allow to do, that lablels don't? This is scheduling by workload - by step. Consider next example:

steps:
  prepare:
    image: alpine
    commands:
      - tar -xf huge_archive.tar
    backend_options:
      kubernetes:
        nodeSelector:
          storage: "nvme" // we need fast storage to extract archive quickly
  build:
    image: golang
    commands:
      - go build
    backend_options:
      kubernetes:
        nodeSelector:
          cpu: "256-core" // we need fast cpu to build quickly
  build:
    image: aws-cli
    commands:
      - aws s3 upload // don't remember exact command
    backend_options:
      kubernetes:
        nodeSelector:
          network: "40Gbit" // we need fast uplink to upload quickly

Taints should be better, but you understand general idea. That is specific use case from my comment.

---

It's time for scheduling via node selector.

matrix:
  PLATFORM:
    - mac/m1
    - windows/amd64

steps:
  build:
    image: golang:${PLATFORM}
    commands:
      - go build
    backend_options:
      kubernetes:
        nodeSelector:
          kubernetes.io/arch: ${PLATFORM}

Interpolates into:

steps:
  build:
    image: golang:mac/m1
    commands:
      - go build
    backend_options:
      kubernetes:
        nodeSelector:
          kubernetes.io/arch: mac/m1

steps:
  build:
    image: golang:windows/amd64
    commands:
      - go build
    backend_options:
      kubernetes:
        nodeSelector:
          kubernetes.io/arch: windows/amd64

Note, that labels are not used (explicitly) at all. Server and Agents run on completely different platfroms than build nodes.

---

Hope, this will help in some way.

[pat-s]

@zc-devs Oh wow, that must have taken you an hour or more 😅 I am a bit overwhelmed almost by that large response. Highly appreciated though!

Overall, I think most of it was already clear to me 😅 I was more focusing on the exact notation with labels only - instead of combining it with the backend_options.
I am referring to this example of yours

matrix:
  PLATFORM:
    - linux/arm
    - windows/amd64

labels:
  platform: ${PLATFORM}

steps:
  build:
    image: golang:${PLATFORM}
    commands:
      - go build

Which sadly does not work when writing it as (which is what I need in my matrix)

### NOT WORKING
matrix:
  include:
    - name: A
      PLATFORM: linux/arm
    - name: B
      PLATFORM: windows/amd64

labels:
  platform: ${PLATFORM}

steps:
  build:
    image: golang:${PLATFORM}
    commands:
      - go build

as it will result in

Execution Error:
failed to parse pipeline: Cannot unmarshal '<nil>' of type <nil> into a string value

This might be a general issue of the include property. In general though I agree that writing it that way would be the "way to go" (as beforehand I was doing it exactly like this but using only platform: ${PLATFORM} instead of labels.platform: ${PLATFORM}).

Interestingly, the above works when ${PLATFORM} is sent to the backend_options and the top-level labels: is not used. Which is why I used the notation in this way for this PR. So maybe it's a backend issue in this specific case of using include within matrix.

And summing @qwerty287 here again due to #2480 - shouldn't the labels.platform: ${PLATFORM} notation work in general and is this potentially a bug? Maybe because the vars are handed over in a map instead of a string in the include: example?

[pat-s]

@zc-devs The current state here is valid code and works (and works around the issue reported when not using backend_options). Hence I'd propose to merge this and update it in another PR (if motivation exists).
You are also welcome to do it, possibly using full examples etc. What do you think?
It's definitely better than before as the current documentation is not resulting in a working YAML.

[zc-devs]

I think that it was an issue. Also I wanted to see more rounded sentences as it is one of the possibilities. And from documentation it should be clear what exactly matters in that case (are there something between matrix and backend options like labels? should they be there?)

merge this and update it in another PR

Why not? There is no blocking from me :)

You are also welcome to do it

May not me? :) Although I would glad to see information from my comment in documentation (with the schemas drawn in a proper way).

[pat-s]

it should be clear what exactly matters in that case (are there something between matrix and backend options like labels? should they be there?

I agree, it could probably be made even more clear. After the labels "bug" is fixed, it should be updated again. But let's get this merged first and refocus :)

Thanks again for all your time invested here! btw: wanna join the maintainers team?

[zc-devs]

wanna join the maintainers team?

Thank you, but may be some time later.