. Personally I really appreciate you taking the time to discuss these issues. Obviously you have your iX hat on and I’m sure we all get that. Especially engaging over your weekends that’s definitely above and beyond.
I would echo @Johnny_Fartpants. I have no problems with “bluntness” - if I did that would be massively hypocritical .
Good things can come out of genuine debate where every side states its case bluntly – and I have no issues with anyone holding differing opinions from myself and then stating them bluntly - but debate only works when people support their point of view with evidence and reasoning, and it also only works when everyone then listens to and considers the points raised by everyone else and is prepared to modify their opinions when the evidence and the arguments warrant it.
The synergies that can come out of such debates can be VERY powerful - because a group mind is capable of greater insight and greater idea generation than any individual - and these can lead to better decisions and fewer issues and less disagreement in the future.
They are in effect a time-machine that can turn hindsight arguments into foresight decisions.
Another point may be that, in switching to the presumably-greener of Linux, iX has taken on some questionable parts of the “Linux ethos”, namely a “move fowards and break things” attitude, the perpetually unstable API that comes out of it, and some confort with exposing experimental features for general use.
That come with some shock to the old FreeBSD users, who were used to have a quite stable appliance which closely tracked the Entrerprise version.
Yes - that is true - and I don’t personally have any problems in principal with this business model BUT it’s not quite that simple…
Users being guinea pigs should be a choice rather than something they do by mistake.
There are loads of people who love being on the bleeding edge and finding and reporting bugs - and that’s great because they know the risks they are taking.
But not everyone who decides to use TrueNAS without paying anything is up for that. Some of us who aren’t up for that, are aware enough not to upgrade without knowing the risks we are taking.
However there is a whole group of people who are not technical and not following the discussions here (because, unlike me, they have a life ). But perhaps they happen across one of the T3 episodes where iX tell them just how brilliant the new 25.04 release is - without any warnings or caveats etc. - so they upgrade and then find something broken. They never signed up to be beta guinea pigs for testing and are entirely ill-equipped to deal with complex problems that arise.
And this large group of people deserve to at least be warned of the risks - and the only way to ensure % that they receive a warning is to give it to them at the actual point of upgrade.
I have several mission critical systems running 13.0-U6.x and they have been great for a good while now but I also have a couple of 24.10.2.x systems running for the last 6 months with the same workload and they have also been solid so far .
Yes, the release notes are a good 1st step, but we realize they are long.
They also don’t map to the user profile of “early adopter” to “conservative”. Rather than retrospectively changing release notes as we learn about software quality, we opted for the software status page. Its the simpler and easier to understand advice.
But it gives me an idea… perhaps we could embed the software status page into the release notes??
Release notes pertains to a release and are frozen in time, software status is dynamic (changes over time). You could however inline the real-time status page into your upgrade process i.e. the current version shown to the user at the point they are about to upgrade. I think even better would be some of the other suggestions further above though.
My personal subjective view is that a single simple title link “Check Release Notes” without any words telling the user they should definitely read them (and definitely without the word “WARNING”) does not meet the dictionary definition of an “exhortation” which is “an address or communication emphatically urging someone to do something”.
The link itself is https : // www . truenas . com / docs / scale / 25.04 / gettingstarted / scalereleasenotes / #25041 which takes you about 80% of the way down the page, to the specifics of this release. If you read this section it talks only about the increments between 25.04.0 and 25.04.1 and the known issues in this section says literally nothing about virtualization. The details about 25.04.0 being “experimental” are in the closed section that looks like this:
but if you open this then there is a warning:
So, I would agree that a cautious user might follow the link and expand the section and spot that they shouldn’t upgrade, but not all users will achieve all these 3 things. IMO it certainly does not rise the the level of “exhortation”.
EDIT: To be completely fair, the phrase “Users with production VMs on TrueNAS 24.10 should not upgrade” is written in 3 separate places on this page, and I think anyone experienced enough to know that they should read the notes and sensible enough to read the release notes in detail should catch on. My point is that not all users are this experienced or this sensible.
Here is a related suggestion:
Consider instead of a single generic link to all update changes that your updater includes all big changes as bullet points with individual links to relevant issues. Ideally showing stacking issues, ie reflecting all major deltas from the version the user is upgrading from to the version that the user is upgrading to.
Ie (as an example, not real life, I know the revisions will be wrong, bear with me I am on an island pecking on my iPhone)
VM:
Core → Scale: nuking of jails
24.10 → 25.4 nuking of VMs
Etc.
In other words, group things logically by category and show all stacking changes. That way, a admin can quickly ignore things that won’t affect them but be aware of major changes that will. In the last three years, most of those changes will be in a relatively small area - ie major networking delta is likely dropping AFP?
But if stacking is enabled, it will really underscore where changes have been made. And hopefully draw attention to same.
I had container IP addressing set up on 24.04 (k3s) and had to endure a really painful migration to 25.04 as the migration window came to a close. I was patiently waiting on “container IP addressing” to land in the catalogue. I also have some VMs that as a result of this migration, mandated I use the incus “experimental” VMs at the same time or have no VM functionality.
here’s how this went:
I migrate from 24.04 → 24.10 → 25.04 in rapid succession, days before the catalogue cutoff, in an aim to have minimal disruption in my apps workflow which is semi-custom and needs custom IP addressing.
since I needed to migrate to 25.04 as a prerequisite, I run into lots of fun problems with the incus VMs system, I eventually get it working but it is a struggle I had to deal with head on. (UTC time vs windows, windows vio driver nightmare, no AHCI drive support (and as a result no optical drive support in some OSes), “importing” of ZVOLs, etc)
I find out that the “Container IP addressing” is really more of a per IP container port binding feature that requires you to add an alias to your host and is not at all useful to my workflow, due to it’s inability of outbound traffic handling. I then have to convert my apps to YAML and fight with creating a network on the CLI that represents my host network and connect my containers to it patching together scraps of documentation into something useful (welcome to unsupported land).
this was all very rough and I could’ve avoided this complete waste of time and stayed on 24.10 for the time being if I knew that:
“Container IP addressing” comes with significant caveats and probably doesn’t do what you think it would.
That there are other ways to accomplish actual Container IP addressing even on 24.10 where I could’ve avoided the VM migration while Incus VMs are experimental.
I Love TrueNAS, but IX seriously needs to work on documentation and expectations, this was pretty rough in combination. (I’ve been a TrueNAS Scale user since the Angelfish RC days, Core user of some many years)
Sorry to hear about your challenges… 24.10.2.2 would have been your best bet. There are probably not that many users with such sophisticated requirements.
If there are documentation holes, we’d very much like users to provide feedback in the docs… It probably won’t help the 1st guy trying something out, but the later travellers may find the nugget they needed.
Is there a section you find inadequate? Have you provided feedback in the docs… any assistance is appreciated.
At present, the relatively good solution for binding the container IP address is to create Macvlan using the command line and then specify the IP through Docker or Docker Compose. However, any modification through the command line is not recommended by TN, and perhaps a certain upgrade will destroy all settings.
I don’t know whether TN will consider this compromise and provide active compatibility when upgrading a certain version in the future.
Regarding TN’s documents, I can only say that these words are better than nothing. These documents are only introduced from the software page, and do not specifically answer their concerns from the user’s perspective.
For example, the page about certificates:
I believe that most users who will use the certificate function have basic computer knowledge, so the purpose of most functions and buttons on the system is self-explanatory. Even if you don’t understand, you can directly obtain information through search engines or GPT.
The documentation just reiterates some obvious functions and buttons, or just introduces the software page, but does not answer several key questions:
What process should I go through to create the certificate I need?
What are the common errors and how to solve them?
Are there complete operation examples corresponding to several common scenarios?
Unfortunately, I have to search for third-party tutorials specifically introducing the TN certificate issuance function, but they are usually old and I need to guess and understand while operating.
Another example is the Bridged NIC and Macvlan NIC on the Incus virtual machine creation page. Clicking the question mark button displays the help information “Enable or disable NICs.” I don’t know what the meaning of this help information is, because I know that checking the box means it is selected.
If I want to create a TN network bridge and connect the network bridge directly to the instance, I will need to solve two problems.
I don’t know that I need to create the network bridge in advance on the network page to see it on the instance page.
The created bridge is displayed under the options of Bridged NIC and Macvlan NIC at the same time, and I don’t know the difference between them.
Yes, there are three sentences of help information on the right side of the page, but I had to try it myself to really understand what these words mean, and it took an hour.
Another issue is the Macvlan of the Incus VM. The Macvlan virtual NIC created through the instance page will appear in the network page, but it cannot be edited, which can be confusing. The name and MAC address of the Macvlan virtual NIC will change after the TN system is restarted, but there is no warning when it is created. If I bind the Macvlan virtual NIC to a network interface in the Incus VM, the services in the VM will be paralyzed after restarting the TN.
I have some suggestions:
The core of the document should be to explain the concept, design and important operations, rather than introducing every obvious option and button.
Add a hyperlink to the corresponding document on each page of the TN system.
Most functions of the TN system are encapsulated based on third-party software, so you can add a hyperlink to the third-party software document to supplement the official TN document.
Introduce TN’s encapsulation and calling form of third-party software in the document, which will help users establish an understanding of the connection between TN and third-party software.
Think about what users want to get from the document from their perspective.
There is a disproportionate focus on documentation here, as if it would be able to compensate for what are in fact significant issues with the actual underlying product and how change is being introduced/managed. There are good examples directly above from both @RetroG and @Apple. The best product is the one that needs no documentation at all. Yes, that is an exaggeration, but you get the drift.
As Morgan said, we’re always happy to get documentation feedback from the community. In fact, you can use the feedback button on any documentation page to submit a ticket directly to the docs team. Or you can use the Edit page button to propose changes yourself.
I do want to clarify though that this page you’re looking at:
is a UI Reference article, meant to provide just that–reference information for the different UI elements on the screen with some limited context provided. Some users want nothing more than that to reference while working on tasks.
The more detailed content you’re looking for is typically available in Tutorials. From the page you were on you can either use the left hand navigation menu to select TrueNAS Tutorials instead of UI Reference Guide:
or scroll to the bottom and view the related Tutorials:
Like I said, we’re happy to take feedback on our docs (and we have ideas in the works to make navigating between the different documentation types easier in the future) but in the meantime I think your experience might improve by knowing where to look for info
The challenge is to avoid killjoy marketing while still adequately warning existing users…
I wanted to let everyone here know that there will be a more direct integration of software status page info in the Goldeye release which should significantly reduce this risk.
It won’t be perfect, but it will be out soon. There will be more details before we get to Goldeye BETA. The irony will be that none of the updates available this year in Goldeye will be “Conservative”
We do have a Time Machine option, but it only works with Macs.