Administering the eLab

For members of elab-admins

This guide is for eLab administrators, who manage desktop capacity, sessions, credits and the budget from the portal's admin page. If you need this and don't hold the role, ask your platform operator to add you; it takes effect the next time you sign in.

Two things this role does not include. Account administration — creating users, granting roles, issuing temporary passwords, resetting a lost authenticator — is done by your platform operator; what users experience is described in the platform's Account Help. And publishing content and choosing your own desktop image are separate roles with their own guides (Publishing Content, Choosing Your Own Image): being an administrator does not imply either, because one is custodianship of everyone's content and the other a personal preference, and neither is running the eLab.

The admin page is arranged in four tabs by concern: Capacity (the desktop pools, warm slots, image choice and the streaming tier), Sessions (who is running now, scheduled starts and their results), Users (per-person controls such as credits) and Budget (spend, the budget and the project end date). The headline numbers sit above the tabs, as does the warning about nodes Azure refuses to add, so both stay visible whichever tab you are on. The page updates itself every few seconds, and the tab you are on is part of the address, so a link such as …/admin#budget opens straight to that tab.

Warming capacity for a scheduled session

Desktops normally provision on demand: a CPU desktop in a couple of minutes, a GPU desktop in around ten from cold. For a scheduled session with many participants, warm capacity in advance from the Capacity tab.

One slot is one desktop's worth of capacity, held ready with the image already downloaded, so a user starting into a warm slot gets a desktop almost immediately. Each desktop type (CPU and GPU) has two controls.

• Reserve — N desktops from a start to an end. Book one per session: for a class or workshop of 30 starting at 09:00, 30 CPU desktops from 08:40 to 12:00. Start it about 20 minutes early for CPU and 30 for GPU, because machines have to join and download the desktop image before a slot counts as ready. Until the end time the reservation holds 30 desktops' worth of capacity whether people are running desktops or not, so someone who stops at lunch and starts again in the afternoon still lands on a warm machine. It ends by itself, and stays in the list marked Ended for a day so you can see what a session that has just finished was given. Reservations that overlap add up.
• Always keep spare — the buffer: that many warm slots beside whatever is running, around the clock, for people arriving through the day. A reservation and the buffer overlap rather than add up: with 30 reserved and a buffer of 5, 30 slots are held until more than 25 people are running desktops, and then 5 spare beside them.

Warm slots never take capacity a user needs: a desktop always takes precedence over one, and no more are held than the room left in the eLab's declared capacity. When a reservation would fill the eLab so that the buffer no longer fits, the page warns you as you book it, and while it is happening the buffer shows how many spare slots are really held, for example Buffer: 10 (3 held — pool nearly full).

Warm capacity bills while it is held, whether or not anyone connects. The page shows what the buffer costs a day and each reservation's total cost, at the deployment's own cost per desktop-hour. Slots people use are charged to their credits as usual, so what a reservation adds is the part nobody uses. GPU capacity is both scarcer and more expensive than CPU. Times are read in your own local time, including across a change of the clocks.

Scheduling desktops for a taught session

Users can book their own desktop to start at a given time from their dashboard. From the Sessions tab you can also book on someone's behalf — for a single user, or for everyone at once ahead of a face-to-face session, so the room is ready when people sit down.

Pick the user (or All users), the desktop type and the time, which is read in your own local time. Booking for everyone replaces any existing bookings those users had made, and the confirmation tells you how many were replaced. Each person is notified on their dashboard.

Two things to keep in mind:

• Credits are drawn from the scheduled time, whether or not anyone connects. Booking a group an hour early costs every participant an hour's credits.
• Only users who have signed in at least once can be scheduled. The platform learns of someone at their first login, so "All users" covers the people it knows about — the count is shown next to the option, and it is worth checking that against the number you expect before relying on it.

Schedule warm capacity for the same time (see above). A booking on its own still starts the desktops cold, so a large block would arrive several minutes late.

The upcoming list shows every booking with the user, type and time, flagging anyone who already has a desktop running. Individual bookings can be cancelled from that list, or all of them at once.

Once a booking fires it is consumed and disappears from the list, so the recent scheduled-start results panel is where you confirm a session actually started. It keeps twelve hours of outcomes and distinguishes desktops that started, ones skipped because a session was already running, and ones that failed — most often because the user had no credits left. That is the panel to check a few minutes after a scheduled start rather than waiting for people to report problems.

Giving users more credits

Every user starts with the same balance of credits, set when the eLab was deployed, and the dashboard shows them what they have left and what it buys. A credit is a penny: every desktop draws credits at its own rate per hour, shown next to its launch button, so a GPU desktop uses its balance faster than a CPU desktop, and the portal warns the user and asks them to confirm before it starts. When someone runs short before a deadline, or a whole group needs more time than planned, add credits from the Credits panel on the Users tab: pick the user (or All users), enter the number of credits, then Apply.

The number is added to what the user has now, so adding 500 to someone with 300 left gives them 800. It takes effect immediately: a desktop that is already running keeps drawing against the new figure, and the user sees a note on their dashboard saying what changed. A negative number takes credits back, but only credits the user still has, so nothing already spent is ever reclaimed and nobody goes below zero. As with scheduling, only users who have signed in at least once are listed. On an eLab that spans several sites, credits are one balance per user wherever their desktop runs, so a top-up follows them.

Two things to keep in mind:

• Credits are money. The budget reconciliation assumes every allocated credit may be spent, so a large top-up for everyone brings forward the point at which the budget throttles everyone. Add what the session needs rather than a generous round number.
• The budget throttle still applies. If the project is overspending, remaining credits are scaled down for everyone regardless of top-ups. Raise the budget first if that is the actual constraint (see Budgets).

When the eLab has more than one site

Some eLabs run desktops at more than one site behind one portal. The Capacity tab then shows a block per site, the portal's own site first, each with its own desktop pools, warm slots, image choice and streaming tier, and every control names the site it applies to. Warm the site where the session will actually run: a user's desktops always start on the site they are placed on, which the eLab team sets by cohort group, so warming the wrong site prepares capacity nobody will use.

The Sessions tab lists desktops from every site with a Site column, and stopping one goes to the right site. Scheduled starts, credits and the budget are the same wherever a user is placed: a booking fires on the user's own site, and the budget is one figure for the whole eLab, with each site's spend added in before the daily reconciliation.

Moving a user to another site. Each user is placed on a site by their cohort group (the platform's name for a placement group, unrelated to a study cohort), and a user in no cohort group is placed on the site of the portal itself. From the Placement panel on the Users tab you can move a user to any site: pick the user and the site, and their next launch starts there. Their files are transferred to the new site straight away, so that first launch is not held up; if the site cannot be reached at that moment, the transfer happens at the first launch instead, and the dashboard tells the user it is running. A transfer keeps the newer copy of each file, whichever site it was edited on, so work done on either side survives a move in both directions. A file deleted on one site returns from the other rather than being removed, so tidy a home after a move rather than before. A move is refused while the user has a desktop running or starting anywhere, because the transfer would write into a home that is in use: stop the desktop from the Sessions tab first. The panel lists everyone who has been moved, with their cohort's site beside the one they are on, and Return to cohort site puts them back; moving someone to their cohort's site does the same. Roles are unaffected by a move, and so are credits and bookings.

A move relocates data — treat it as a decision, not a convenience. The sites of one eLab may sit in different regions or countries, and a move copies the user's whole home directory to the new one. That includes anything they have copied out of their approved imports, which they are free to do: imports are read-only, but reading them is the point, and nothing in the portal can prevent a copy into their own home. So the moment of moving someone is where the decision actually gets made. Before moving people between sites, satisfy yourself that the project's data agreement allows their data to sit at the destination, and consider whether any export controls apply. If in doubt, ask your data governance officer before moving rather than after.

What a move does not carry is /imports: approved airlock imports live on a separate share, not in the home directory, so they stay at the site they were delivered to. The user keeps whatever they copied into their home, and can request the import again on the new site — there is one airlock for the whole eLab, so their request history moves with them even though the files do not.

While a transfer is running the Placement panel names the user and the site their files are moving to, and the user cannot launch until it finishes. Most moves show nothing here at all: if the user's files are already on the destination, from an earlier session there, the move says so and transfers nothing. A transfer that fails is flagged in the same place, in amber. Their desktop will not start on that site until it succeeds, so move them again to retry.

A site that cannot be reached is marked unreachable on the Capacity tab and its sessions are not listed. Desktops already running there carry on. Nothing on that site can be changed from the portal until it is back, and its users see the same message on their dashboards.

Checking capacity before a session

On the Capacity tab, each desktop type shows how many nodes it is currently using out of the maximum it is allowed to grow to. When a pool reads at ceiling, desktops that will not start are hitting a configured limit rather than waiting for capacity to arrive, and no amount of waiting will clear them — that needs a configuration change, so raise it with the platform team ahead of the session rather than during it.

A different failure looks identical from the outside: the pool is still below its ceiling, but Azure will not create the nodes. When that happens a banner reads Azure is refusing to add nodes, naming the pool and the reason. Take it at face value — desktops and warm slots beyond what the running nodes already hold will wait indefinitely rather than start, and capacity showing as provisioning for that pool is not on its way.

The two reasons differ in what you can do about them:

• Quota used up — the subscription is allowed no more vCPUs of that VM size. Only a quota increase clears it, which the platform team must request from Azure and which is not granted immediately. Plan the session around the capacity you already have.
• No regional capacity — Azure has none of that VM size free at the moment. This usually clears on its own, and where a pool with a different VM size is configured the platform will try that one instead.

Without this banner neither is visible: a refused scale-up and a merely slow one both leave warm slots reading provisioning.

Users see a matching, plainer version of this on their own dashboard: a desktop with no machine available reads Waiting for capacity rather than a permanent Starting…, and after about half an hour the platform stops waiting, removes it and tells them why. No hours are charged for a desktop that never ran. Expect people whose desktops were removed this way to ask you when capacity will be back — the banner above is where you find out.

The streaming tier panel reports the components that carry desktop screens to the browser, as ready-out-of-expected counts. These are sized in advance rather than grown on demand, so anything short of the expected number means the platform is running with less streaming capacity than intended. It will not be obvious to users until a session is busy, at which point connections start failing — so check this reads fully ready before a large session, and report a shortfall rather than working around it.

Choosing desktop images

Where more than one desktop image is offered for a pool (for example a full and a lite CPU image, or PyTorch and TensorFlow GPU images), the Capacity tab selects which image new launches use. Pick the image before warming capacity — warmed sessions are prepared with the selected image. Running desktops keep the image they started with.

Letting someone choose their own. A member of elab-image-managers can override the pool's image for their own desktops only — useful for someone leading a group who wants the full workstation while the group runs on the lite image, or for testing a new image before switching everyone to it. Nothing you set here changes for anyone else. Choosing Your Own Image is their guide, and worth sending them: it covers why their desktop starts more slowly than everyone else's.

What each image carries is described for users in Tools on the Desktop. In short: the full CPU image is a complete workstation (JupyterLab, VS Code, RStudio and R, conda, LibreOffice); the lite image is Firefox, VS Code and plain Python with pip, at under half the size, which makes it the better choice for a taught session where people only need an editor and a browser; and each GPU image is the full image plus one framework, PyTorch or TensorFlow, never both.

Your eLab's own images. The list is not limited to the images the platform ships. An eLab can declare its own — a discipline's toolchain on top of the standard desktop, say — and they appear in the same picker under whatever name your operator gave them, with no change to the platform itself. Ask your operator what an image carries before selecting it for a pool: only they can tell you, and users will read the list as though the platform vouched for it.

Budgets

Desktop time draws down the project budget automatically through credits; users see their remaining credits in the portal, and new desktops stop launching when the budget is exhausted.

The budget itself starts from the value your operator set when the eLab was deployed, and the Budget tab shows the figure in force. You can override it there: enter a new total (ex-VAT) and choose Set. The change does not take effect instantly — the platform reconciles spend against the budget on a schedule, and the page marks the new figure applies at next recalculation until that has run. Choose Recalculate now to bring it forward; spend and the users' hour allowances refresh within a minute or two.

The fixed monthly cost is the standing bill for the infrastructure itself — the cluster's base nodes, storage, gateway — and it is reserved out of the total before any of it pays for desktop hours. Setting it here works like the budget: enter the monthly figure and choose Set, and it applies at the next recalculation. Raise it and there is less left for desktops, so everyone's hour allowance falls; lower it and more becomes available. The page refuses a figure that would consume the whole budget over the project's length, since that would leave no hours for anyone at all.

The project end date sits below and works the same way: the budget is paced from the project start to this date, so extending a project that overruns, or shortening one that ends early, changes how fast the remaining budget may be spent. Set the new date and it applies at the next recalculation. The start date cannot be changed, because spend is measured from it. The page refuses a date in the past or one before the project start.

An override entered here wins over the deployed value, and stays in force until you change it again. Because it changes how many credits everyone is allowed, treat it as a deliberate decision rather than a quick fix for a group that has run out — and tell your operator, so the deployed value can be brought into line.

Where the platform cannot read actual spend (the page says so, and names the reason), the budget is still the figure hours are scaled against; only the spend-based throttling is paused.

Cost per desktop-hour. Lower on the same tab is what an hour of each desktop class costs, in credits, which is what a running desktop draws down. It starts from the figure your operator deployed and can be set here; the deployed number stays shown beside it whenever the two differ, and Use deployed puts it back. Changing it applies to desktops started from then on, so a running desktop keeps the rate it started at, and everyone's hours-remaining figure moves as soon as you set it even though no credits change hands. Where an eLab spans several sites the drain is decided centrally, so this one figure covers desktops wherever they run: if the sites differ in price, use an average weighted by the desktop slots each one declares, and prefer to round up, since a rate set too low shows up later as everyone's allowance being cut part-way through.

On an eLab that spans several sites there is one budget for the whole eLab, managed on this page; each site's own spend is included in the reconciliation.

Helping a user with their desktop

Administrators cannot attach to a user's desktop session. There is no such control on the admin page, and this is deliberate: a desktop may show confidential data, and silent access to it — even by an administrator — is not something the platform offers.

When someone needs help with what is on their screen, ask them to share it with you. From their own portal page they choose Share my screen (view only) and send you the link. You will need to sign in to the portal to open it, you will be able to see but not control their desktop, and the platform records that you viewed it. The link works once and expires after ten minutes, so ask for a fresh one rather than keeping an old link.

The one desktop control administrators do have is stopping a session, which is visible to the user because their desktop disappears. Use it to recover a stuck or abandoned session, not as a way to interrupt someone — and tell them you have done it.