refactor: podman quadlet sub-command by axel7083 · Pull Request #28335 · containers/podman

axel7083 · 2026-03-20T18:17:50Z

Checklist

Ensure you have completed the following checklist for your pull request to be reviewed:

Certify you wrote the patch or otherwise have the right to pass it on as an open-source patch by signing all
commits. (git commit -s). (If needed, use git commit -s --amend). The author email must match
the sign-off email address. See CONTRIBUTING.md
for more information.
Referenced issues using Fixes: #00000 in commit message (if applicable)
Tests have been added/updated (or no tests are needed)
Documentation has been updated (or no documentation changes are needed)
All commits pass make validatepr (format/lint checks)
Release note entered in the section below (or None if no user-facing changes)

Does this PR introduce a user-facing change?

refactor the podman quadlet command

While working on #28117 and the comment from @Luap99 (#28117 (comment)) I had a lot of issues working around the .app and .asset file, a suggestion made was to get rid of those and consider an application as a folder.

Here is a POC / proposal of how it could works

`podman quadlet install`

When trying to install from a directory, you will need to specify --application as we want to avoid dumping all the content of the directory at the root.

Installing from a directory (support recursive)

$: podman quadlet install --application flask-redis ./flask-redis
$: ree /home/axel7083/.config/containers/systemd
/home/axel7083/.config/containers/systemd
└── flask-redis
    ├── app
    │   ├── app.py
    │   ├── Containerfile
    │   └── requirements.txt
    ├── flask.kube
    ├── play.yaml
    └── README.md

`podman quadlet ls --format=json`

Following flask-redis installed above we get

$: podman quadlet ls --format=json
[
  {
    "Name": "flask.kube",
    "UnitName": "flask.service",
    "Path": "/home/axel7083/.config/containers/systemd/flask-redis/flask.kube",
    "Status": "inactive/dead",
    "App": "flask-redis" <-- application name is the name of the sub directory
  },
]

Now let's add an nginx.image

$: podman quadlet install ./nginx.image
$: podman quadlet ls --format=json
[
  {
    "Name": "flask.kube",
    "UnitName": "flask.service",
    "Path": "/home/axel7083/.config/containers/systemd/flask-redis/flask.kube",
    "Status": "inactive/dead",
    "App": "flask-redis"
  },
  {
    "Name": "nginx.image",
    "UnitName": "nginx-image.service",
    "Path": "/home/axel7083/.config/containers/systemd/nginx.image",
    "Status": "inactive/dead",
    "App": "" <-- No application name as it is at the root
  }
]

⚠️ this is only taking the first directory, if we have /home/axel7083/.config/containers/systemd/flask-redis/nested/flask.kube" it will still be flask-redis.

`podman quadlet rm`

I added a --recursive option, the rm support two input, a quadlet file (E.g. foo.image) or an application name. However when trying t o delete an application it will throw an error

$: /bin/podman quadlet rm flask-redis
Error: unable to remove Quadlet: cannot find application "flask-redis"

You need to specify the --recursive flag to delete the quadlets in the application

I did not in this POC deleted the full application directory, I was not sure, open to suggestion

Luap99

Only a short high level look I am definitely in favour of this directory approach.

Question do we care about backwards compatibility? We still have 3-4 weeks till podman6 so we can break if wanted. And given quadlet install is a rather new command maybe reworking that now without worrying about compatibility is the easiest.

cc @mheon

mheon · 2026-03-23T22:17:36Z

Ummm. Given how new these commands are, it would not be unprecedented to break folks, but it's still a very bad user experience...

Our migration options are also not particularly pretty though. I suppose we could detect legacy project files and convert to a directory and remove the file on finding them?

Luap99 · 2026-03-24T11:58:33Z

Our migration options are also not particularly pretty though. I suppose we could detect legacy project files and convert to a directory and remove the file on finding them?

Convert when? "inside quadlet"? when running "podman quadlet list/install/remove"? For install/remove it is not clear to me we should migrate other files. And on list it seems strange to do a rewrite of files, i.e. there is no sane way to make this in a atomic fashion so we risk leaving the files in a bad state when getting killed.

simonbrauner · 2026-03-25T13:07:56Z

I also like using directories instead of the .app files, introducing the --application option instead depending on directory name, as well as removing the If a quadlet is part of an application, removing that specific quadlet will remove the entire application. functionality.

Service naming conflicts

But this introduces the possibility of having multiple services of the same name.

$ podman quadlet install postgres-17-test --application=a
/home/sbrauner/.config/containers/systemd/a/A.container
/home/sbrauner/.config/containers/systemd/a/B.container
/home/sbrauner/.config/containers/systemd/a/README.md
$ podman quadlet install postgres-17-test --application=b
/home/sbrauner/.config/containers/systemd/b/A.container
/home/sbrauner/.config/containers/systemd/b/B.container
/home/sbrauner/.config/containers/systemd/b/README.md
$ podman quadlet list
ERRO[0000] Unexpected unit returned by systemd - was not searching for A.service 
ERRO[0000] Unexpected unit returned by systemd - was not searching for B.service 
NAME         UNIT NAME   PATH ON DISK                                             STATUS         APPLICATION
A.container  A.service   /home/sbrauner/.config/containers/systemd/b/A.container  inactive/dead  b
B.container  B.service   /home/sbrauner/.config/containers/systemd/b/B.container  inactive/dead  b
             A.service                                                            inactive/dead  
             B.service                                                            inactive/dead

So I suppose it should either check for naming conflicts, or make the application name part of the service name, so that multiple quadlets with the same application-local name can exist independently.

Implicit merge of applications

I am also thinking that maybe it would be slightly more convenient for the user if they were notified that they are adding quadlets to an existing application. Now it happens implicitly, so it can hypothetically happen that the user:

creates application `webserver`, with containers `A` and `B`
forgets about it
creates different application and decides to also call it `webserver`, with containers `C` and `D`
removes `webserver`, thinking they are removing `C` and `D`, but `A` and `B` would also get removed.

simonbrauner · 2026-04-22T16:20:02Z

Also took a mostly high level look, it looks nice overall.

It does not look like it's ready to be merged, there are TODOs.

My previous comment should probably be addressed, as installing multiple quadlets with the same name breaks.

Removing the whole application keeps non-quadlet files and the directory itself.

The word refactor does not seem right, as this changes functionality.

axel7083 · 2026-04-28T13:23:38Z

Hey @simonbrauner !

It does not look like it's ready to be merged, there are TODOs.

I removed the TODOs

My previous comment should probably be addressed, as installing multiple quadlets with the same name breaks.

This is something already possible with the current, so not sure how this could been addressed? Maybe we need a dedicated issue to try to address that?

Removing the whole application keeps non-quadlet files and the directory itself.

It does if there is no errors while removing each quadlet in the application, the directory will be removed 👍

podman/pkg/domain/infra/abi/quadlet.go

Lines 626 to 637 in 5d12165

    
           // clean up application folder when no error 
        
           if len(report.Errors) == 0 { 
        
           	appPath, err := getApplicationPath(quadlet) 
        
           	if err != nil { 
        
           		report.Errors[quadlet] = err 
        
           	} else { 
        
           		err = os.RemoveAll(appPath) 
        
           		if err != nil { 
        
           			report.Errors[quadlet] = err 
        
           		} 
        
           	} 
        
           }

packit-as-a-service · 2026-04-28T13:30:06Z

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

simonbrauner · 2026-04-29T13:49:05Z

Hello @axel7083.

I removed the TODOs

There is still one about validation of application name https://github.com/containers/podman/pull/28335/changes#diff-98a6e1ecc741f449262cca173c6e557c64dbf2706e5b062967b07b76018b62adR10

This is something already possible with the current, so not sure how this could been addressed? Maybe we need a dedicated issue to try to address that?

I would say this is introduced by the possibility of having multiple quadlets of the same name across different applications.

With the original approach, installing multiple quadlets of the same name fails:

$ podman quadlet install postgres-17-test
/home/sbrauner/.config/containers/systemd/README.md
/home/sbrauner/.config/containers/systemd/A.container
/home/sbrauner/.config/containers/systemd/B.container

$ podman/bin/podman quadlet install postgres-17-test-2
Error: quadlet "postgres-17-test-2/A.container" failed to install: a Quadlet with name A.container already exists, refusing to overwrite
Error: quadlet "postgres-17-test-2/B.container" failed to install: a Quadlet with name B.container already exists, refusing to overwrite
Error: quadlet "postgres-17-test-2/README.md" failed to install: a Quadlet with name README.md already exists, refusing to overwrite
Error: errors occurred installing some Quadlets

So I am thinking, the two ideas would be:

Check if quadlet of that name exists anywhere regardless of the application and fail if it does.
Add some prefix to the unit name, so that systemd is not confused, for example a/A.service and b/A.service would be two separate services which just happen to have the same file name of a corresponding quadlet, but can coexist independently.

But I am not saying this is something that has to be done as part of this PR, I was just thinking of the consequences of your changes and this is what I thought of.

It does if there is no errors while removing each quadlet in the application, the directory will be removed 👍

👍

axel7083 · 2026-04-29T15:50:07Z

So I am thinking, the two ideas would be:

Check if quadlet of that name exists anywhere regardless of the application and fail if it does.

I will try to add this tomorrow morning 👍

axel7083 · 2026-04-29T17:15:03Z

@simonbrauner I reviewed the problem, and the current behavior that you are seeing is not preventing "duplicate" quadlets with the same service name, but rather preventing you to override, the logic is technically still here.

If you try to podman quadlet install ./foo.image twice with the change you will get the same error.

podman/pkg/domain/infra/abi/quadlet.go

Lines 285 to 287 in af3ed8d

    
           if errors.Is(err, fs.ErrExist) { 
        
           	return "", fmt.Errorf("a Quadlet with name %s already exists, refusing to overwrite", filepath.Base(finalPath)) 
        
           }

The problem of duplicates service name is a bit more annoying to solve, let me explain. A service name is either define by its name or by its Service=<name> key.

The quadlet systemd generator is reading and parsing the unit file, and lookup for the Service key in the [Unit] group as shown bellow

podman/pkg/systemd/quadlet/quadlet.go

Lines 1580 to 1590 in 2cc3be7

    
           func getServiceName(quadletUnitFile *parser.UnitFile, groupName string, defaultExtraSuffix string) string { 
        
           	if serviceName, ok := quadletUnitFile.Lookup(groupName, KeyServiceName); ok { 
        
           		return serviceName 
        
           	} 
        
           	baseServiceName := removeExtension(quadletUnitFile.Filename, "", "") 
        
           	if baseServiceName[len(baseServiceName)-1] == '@' { 
        
           		baseServiceName = baseServiceName[:len(baseServiceName)-1] 
        
           		defaultExtraSuffix += "@" 
        
           	} 
        
           	return baseServiceName + defaultExtraSuffix 
        
           }

But for us this is a little bit a challenge, as when should we fails? If the user is installing foo.image and bar.image and they both have Service=hello.service this is a problem, and currently one will be randomly picked (I reported the problem in #28118).

So my question would be, when should we fails?

If the user already have multiple quadlets with the same service name, if we try to install another should we fail?

Does the quadlet generator should fail if multiple quadlets have the same service name? Or just a warning in the stderr?

I think we can parse every quadlets we try to install and check that in the list of quadlets we try to install (when passing a directory or a tar) we could read and parse them, but what if they are invalid? currently I don't think we are checking if the quadlets files are valid 🤔 .

Anyway, I think this is going a bit out of scope of this PR, and as it is already big enough, I think we may skip the service name issue, wdyt?

simonbrauner · 2026-04-30T07:35:18Z

Anyway, I think this is going a bit out of scope of this PR, and as it is already big enough, I think we may skip the service name issue, wdyt?

Yes, sure. Initially I thought that this is strange behavior introduced by this PR, but if it's just something that was there already (just less likely to happen), then I have nothing against considering it out of scope.

packit-as-a-service · 2026-05-04T09:02:54Z

Cockpit tests failed for commit c026ffc. @martinpitt, @jelly, @mvollmer please check.

packit-as-a-service · 2026-05-04T09:13:54Z

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

simonbrauner · 2026-05-04T15:43:50Z

@axel7083 I had similar CI failures and it got solved by rebasing on the latest main.

Luap99

not a very deep review, one minor thing for the docs

logic wise LGTM overall though I did not test thoroughly

cc @inknos ref #28627

mheon · 2026-05-12T17:46:01Z


+#### **--recursive**
+
+When an application name is specified, you need to specify --recursive flag to remove all the Quadlets which belongs to that specific application.


This reads a bit confusing. Is this mandatory when an application name is specified, and does nothing otherwise? If so, do we need the dedicated argument? User intent in specifying an application seems pretty clear that they want everything gone

I agree, this is probably an option that can be on by default if an application requires it it makes sense to have it on and documented

Thank you for you feedback and for what it's worth I think that's confusing too.

The flag is required when the user removes an application (the folder, recursively). And it's not required when the user wants to delete a single quadlet (i.e. podman quadlet rm flask.container flask.volume works fine).

The rationale for requiring this flag in the case of an application is to ensure that the user understands the implications of the removal: rm -rf <app-folder>.

Hm. As long as we have clear error messages telling folks to use --recursive when they try and remove an app, I can live with it.

This is the current error:

$ podman quadlet rm foo Error: unable to remove Quadlet: refusing to remove application "foo": recursive option is not set

And I have simplified the documentation of the --recursive flag:

#### **--recursive** Required when removing applications (default false)

inknos

what happens if you do
podman quadlet install --application nameofapp.container directory/ and you have installed nameofapp.container already?

I know that disambiguation is an issue we'll have to deal with eventually out of this PR, but it makes sense to me to at least check for valid application names that can collide with quadlet files. I could definitely see a user calling "container" their application and running into an unexpected collision.

inknos · 2026-05-13T09:33:17Z


+#### **--recursive**
+
+When an application name is specified, you need to specify --recursive flag to remove all the Quadlets which belongs to that specific application.


I agree, this is probably an option that can be on by default if an application requires it it makes sense to have it on and documented

l0rd · 2026-05-13T12:22:10Z

what happens if you do podman quadlet install --application nameofapp.container directory/ and you have installed nameofapp.container already?

I know that disambiguation is an issue we'll have to deal with eventually out of this PR, but it makes sense to me to at least check for valid application names that can collide with quadlet files. I could definitely see a user calling "container" their application and running into an unexpected collision.

Do you mean we should avoid installing an application whose name would be a valid quadlet name? Or that we should check the names of the existing quadlets (not services) and avoid collisions?

inknos · 2026-05-13T13:37:31Z

Do you mean we should avoid installing an application whose name would be a valid quadlet name? Or that we should check the names of the existing quadlets (not services) and avoid collisions?

Avoid the application has a valid quadlet name, like it should not end with .container,.pod, etc

l0rd · 2026-05-13T21:48:50Z

Avoid the application has a valid quadlet name, like it should not end with .container,.pod, etc

I have added this condition to the function that validates application names and a new unit test as well.

Fixes: containers#28118 Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com>

github-actions Bot added the kind/api-change Change to remote API; merits scrutiny label Mar 20, 2026

Luap99 reviewed Mar 23, 2026

View reviewed changes

simonbrauner mentioned this pull request Mar 25, 2026

Quadlet no longer part of Application Group after removal and reinstallation #27573

Open

axel7083 force-pushed the refactor/quadlet-applications branch 6 times, most recently from df7607c to 42c6321 Compare April 13, 2026 12:29

axel7083 changed the title ~~refactor: podman quadlet sub-command WIP / POC~~ refactor: podman quadlet sub-command Apr 13, 2026

axel7083 marked this pull request as ready for review April 13, 2026 13:09

axel7083 requested a review from Luap99 April 13, 2026 13:09

Luap99 added the 6.0 Breaking changes for Podman 6.0 label Apr 21, 2026

axel7083 force-pushed the refactor/quadlet-applications branch from 42c6321 to 5d12165 Compare April 28, 2026 13:14

axel7083 force-pushed the refactor/quadlet-applications branch from 5d12165 to af3ed8d Compare April 28, 2026 13:25

axel7083 force-pushed the refactor/quadlet-applications branch 3 times, most recently from 2fd9762 to 97fcbb6 Compare April 30, 2026 07:18

axel7083 force-pushed the refactor/quadlet-applications branch from 97fcbb6 to c026ffc Compare May 4, 2026 08:38

Honny1 reviewed May 4, 2026

View reviewed changes

axel7083 force-pushed the refactor/quadlet-applications branch from c026ffc to 8f0ef82 Compare May 5, 2026 07:20

axel7083 requested a review from Honny1 May 5, 2026 09:41

Honny1 reviewed May 6, 2026

View reviewed changes

Comment thread pkg/domain/infra/abi/quadlet.go

Comment thread pkg/domain/infra/abi/quadlet.go Outdated

Comment thread cmd/podman/quadlet/remove.go Outdated

Comment thread test/apiv2/36-quadlets.at Outdated

Comment thread cmd/podman/quadlet/remove.go Outdated

l0rd mentioned this pull request May 12, 2026

Fix(quadlet): Ensure .app application file is removed by quadlet rm --all (#27647) #27694

Closed

6 tasks

l0rd force-pushed the refactor/quadlet-applications branch 3 times, most recently from e2a13c5 to 2317792 Compare May 12, 2026 12:36

Luap99 reviewed May 12, 2026

View reviewed changes

Comment thread cmd/podman/quadlet/remove.go Outdated

Comment thread pkg/api/handlers/libpod/quadlets.go Outdated

mheon reviewed May 12, 2026

View reviewed changes

inknos reviewed May 13, 2026

View reviewed changes

l0rd force-pushed the refactor/quadlet-applications branch from 2317792 to 73ce7ff Compare May 13, 2026 21:28

feat: update podman quadlet sub-command

6079157

Fixes: containers#28118 Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com>

l0rd force-pushed the refactor/quadlet-applications branch from 73ce7ff to 6079157 Compare May 13, 2026 21:55


		#### --recursive

		When an application name is specified, you need to specify --recursive flag to remove all the Quadlets which belongs to that specific application.

Conversation

axel7083 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Does this PR introduce a user-facing change?

podman quadlet install

podman quadlet ls --format=json

podman quadlet rm

Uh oh!

Luap99 left a comment

Choose a reason for hiding this comment

Uh oh!

mheon commented Mar 23, 2026

Uh oh!

Luap99 commented Mar 24, 2026

Uh oh!

simonbrauner commented Mar 25, 2026

Service naming conflicts

Implicit merge of applications

Uh oh!

simonbrauner commented Apr 22, 2026

Uh oh!

axel7083 commented Apr 28, 2026

Uh oh!

packit-as-a-service Bot commented Apr 28, 2026

Uh oh!

simonbrauner commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

axel7083 commented Apr 29, 2026

Uh oh!

axel7083 commented Apr 29, 2026

Uh oh!

simonbrauner commented Apr 30, 2026

Uh oh!

packit-as-a-service Bot commented May 4, 2026

Uh oh!

packit-as-a-service Bot commented May 4, 2026

Uh oh!

simonbrauner commented May 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Luap99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mheon May 12, 2026

Choose a reason for hiding this comment

Uh oh!

inknos May 13, 2026

Choose a reason for hiding this comment

Uh oh!

l0rd May 13, 2026

Choose a reason for hiding this comment

Uh oh!

mheon May 13, 2026

Choose a reason for hiding this comment

Uh oh!

l0rd May 13, 2026

Choose a reason for hiding this comment

Uh oh!

l0rd May 13, 2026

Choose a reason for hiding this comment

Uh oh!

inknos left a comment

Choose a reason for hiding this comment

Uh oh!

inknos May 13, 2026

Choose a reason for hiding this comment

axel7083 commented Mar 20, 2026 •

edited

Loading

`podman quadlet install`

`podman quadlet ls --format=json`

`podman quadlet rm`

simonbrauner commented Apr 29, 2026 •

edited

Loading